Openclaw.json文件终极配置指南：Gateway稳定启动+阿里云/本地部署+千问/Coding Plan全配置-阿里云开发者社区

一、前言

很多新手初次使用 OpenClaw（Clawdbot），90% 都会卡在同一个地方：openclaw.json 配置写错导致 Gateway 起不来。字段太多、层级太深、格式敏感、未知字段直接拒绝启动，让人无从下手。

本文严格保留核心配置逻辑、结构、字段含义与最佳实践，同时完整加入：

2026 阿里云轻量服务器零基础部署
Windows11 / MacOS / Linux 本地一键部署
阿里云千问大模型 API 完整配置
免费大模型 Coding Plan API 配置
可直接复制的配置模板 + 命令
新手最常见报错与一键修复方案

全文新手照着抄就能让 Gateway 稳稳启动。阿里云部署 OpenClaw 只需两步，全网最简单，步骤流程访问阿里云OpenClaw一键部署专题页面 了解。
OpenClaw部署教程图1.png

二、先搞懂：openclaw.json 到底是什么

文件位置：~/.openclaw/openclaw.json
格式：JSON5（支持注释、 trailing comma 尾逗号）
特点：极其严格，多一个未知字段、少一个引号、层级错一层，Gateway 直接启动失败。

它一共管理 8 大核心模块：

channels：接入哪些平台（Discord/Slack/WhatsApp/Telegram/飞书）
agents：你有几个智能体、用什么模型、工作区在哪
models：模型提供商、API Key、模型列表
gateway：端口、鉴权、热重载策略
cron：定时任务
bindings：消息路由（哪个渠道发给哪个 Agent）
env：环境变量与密钥
skills/plugins：技能与插件开关

下面直接给可落地、可直接复制的最简稳定版配置。

三、完整版 openclaw.json 稳定模板（直接复制使用）

{
   
  "gateway": {
   
    "port": 18789,
    "auth": {
   
      "mode": "token",
      "token": "your-gateway-token"
    },
    "reload": {
   
      "mode": "hybrid"
    }
  },
  "agents": {
   
    "defaults": {
   
      "model": {
   
        "primary": "bailian/qwen3-max"
      },
      "maxConcurrent": 20
    },
    "list": [
      {
   
        "id": "default-agent",
        "workspace": "~/.openclaw/workspace/default",
        "identity": {
   
          "name": "AI助手",
          "emoji": "🤖"
        }
      }
    ]
  },
  "models": {
   
    "mode": "merge",
    "providers": {
   
      "bailian": {
   
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-你的阿里云千问APIKey",
        "models": [
          {
   
            "id": "qwen3-max",
            "contextWindow": 8192,
            "maxTokens": 2048
          }
        ]
      },
      "coding-plan": {
   
        "baseUrl": "https://api.codingplan.ai/v1",
        "apiKey": "你的CodingPlan免费APIKey",
        "models": [
          {
   
            "id": "coding-free",
            "contextWindow": 4096,
            "maxTokens": 1024
          }
        ]
      }
    }
  },
  "channels": {
   
    "discord": {
   
      "enabled": false,
      "token": "",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist"
    },
    "slack": {
   
      "enabled": false,
      "botToken": "",
      "appToken": "",
      "dmPolicy": "pairing"
    },
    "whatsapp": {
   
      "enabled": false,
      "dmPolicy": "pairing",
      "allowFrom": [],
      "groups": {
   
        "*": {
   
          "requireMention": true
        }
      }
    }
  },
  "bindings": [
    {
   
      "agentId": "default-agent",
      "match": {
   
        "channel": "*"
      }
    }
  ],
  "cron": [],
  "env": {
   
    "vars": {
   }
  }
}

四、八大模块逐行看懂（新手必学）

1. gateway：网关入口

"gateway": {
   
  "port": 18789,
  "auth": {
    "mode": "token", "token": "自定义密码" },
  "reload": {
    "mode": "hybrid" }
}

port：默认 18789，必须放行防火墙
auth：面板访问鉴权
reload：hybrid 最稳定（安全配置热重载，关键配置自动重启）

2. agents：智能体定义

"agents": {
   
  "defaults": {
   
    "model": {
    "primary": "bailian/qwen3-max" }
  },
  "list": [{
    "id": "default-agent", "workspace": "~/.openclaw/workspace/default" }]
}

id：唯一标识，用于路由绑定
workspace：每个 Agent 独立目录，互不污染

3. models：模型提供商（最关键）

支持同时配置阿里云千问 + 免费 Coding Plan，自动兜底。

4. channels：消息渠道

每个平台统一策略：

dmPolicy：pairing（需管理员同意）最安全
groupPolicy：allowlist（仅白名单群可用）
requireMention：必须@才回复，防骚扰

5. bindings：路由规则

把所有渠道消息都交给 default-agent：

{
   
  "agentId": "default-agent",
  "match": {
    "channel": "*" }
}

6. cron：定时任务

示例：每天早上 10 点执行任务

{
   
  "id": "daily-report",
  "enabled": true,
  "schedule": "0 10 * * *",
  "payload": {
   
    "kind": "systemEvent",
    "text": "生成今日工作简报"
  }
}

7. env：环境变量

存放 API Key、第三方 Token，更安全。

8. skills/plugins：技能开关

统一在面板启用，无需手动写 JSON。

五、2026 阿里云轻量服务器部署 OpenClaw（零基础 10 分钟）

步骤 1：购买实例

阿里云控制台 → 轻量应用服务器
镜像：应用镜像 → OpenClaw 2026 稳定版
地域：中国香港 / 新加坡
配置：2核2GB、40GB、5Mbps
设置 root 密码，记录公网IP

阿里云用户零基础部署 OpenClaw 喂饭级步骤流程

第一步：点击打开访问阿里云OpenClaw一键部署专题页面。

第二步：打开选择阿里云轻量应用服务器，配置参考如下：

镜像：OpenClaw(Moltbot)镜像（已经购买服务器的用户可以重置系统重新选择镜像）
实例：内存必须2GiB及以上。
地域：默认美国（弗吉尼亚），目前中国内地域（除香港）的轻量应用服务器，联网搜索功能受限。
时长：根据自己的需求及预算选择。

轻量应用服务器OpenClaw镜像.png

第三步：打开访问阿里云百炼大模型控制台，找到密钥管理，单击创建API-Key。

阿里云百炼密钥管理图.png

前往轻量应用服务器控制台，找到安装好OpenClaw的实例，进入「应用详情」放行18789端口、配置百炼API-Key、执行命令，生成访问OpenClaw的Token。
阿里云百炼密钥管理图2.png

端口放通：需要放通对应端口的防火墙，单击一键放通即可。
配置百炼API-Key，单击一键配置，输入百炼的API-Key。单击执行命令，写入API-Key。
配置OpenClaw：单击执行命令，生成访问OpenClaw的Token。
访问控制页面：单击打开网站页面可进入OpenClaw对话页面。

阿里云百炼Coding Plan API-Key 获取、配置保姆级教程：

创建API-Key，推荐访问订阅阿里云百炼Coding Plan，阿里云百炼Coding Plan每天两场抢购活动，从按tokens计费升级为按次收费，可以进一步节省费用！

购买后，在控制台生成API Key。注：这里复制并保存好你的API Key，后面要用。
回到轻量应用服务器-控制台，单击服务器卡片中的实例 ID，进入服务器概览页。
在服务器概览页面单击应用详情页签，进入服务器详情页面。
端口放通在OpenClaw使用步骤区域中，单击端口放通下的执行命令，可开放获取OpenClaw 服务运行端口的防火墙。
这里系统会列出我们第一步中创建的阿里云百炼 Coding Plan的API Key，直接选择就可以。
获取访问地址单击访问 Web UI 面板下的执行命令，获取 OpenClaw WebUI 的地址。

步骤 2：放行 18789 端口

firewall-cmd --add-port=18789/tcp --permanent
firewall-cmd --reload
firewall-cmd --list-ports | grep 18789

步骤 3：初始化 OpenClaw

docker exec -it openclaw bash
openclaw init --full
openclaw --version
exit

docker update --restart=always openclaw
docker restart openclaw

步骤 4：访问面板

http://你的公网IP:18789

六、Windows11 / MacOS / Linux 本地部署

Windows11（管理员 PowerShell）

Set-ExecutionPolicy Bypass -Scope Process -Force
iwr -useb https://openclaw.ai/install.ps1 | iex
openclaw onboard --install-daemon
openclaw gateway start

MacOS

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install docker node
open /Applications/Docker.app

docker pull openclaw/openclaw:2026.3.26
mkdir -p ~/OpenClaw/{
   config,workspace,skills}

docker run -d \
--name openclaw \
--restart always \
-p 18789:18789 \
-v ~/OpenClaw/config:/app/config \
-v ~/OpenClaw/workspace:/app/workspace \
-v ~/OpenClaw/skills:/app/skills \
openclaw/openclaw:2026.3.26

Linux（Ubuntu/Debian）

sudo apt update
curl -fsSL https://get.docker.com | bash
sudo systemctl enable docker && sudo systemctl start docker

sudo mkdir -p /opt/openclaw/{
   config,workspace,skills}
sudo chmod -R 777 /opt/openclaw

sudo docker run -d \
--name openclaw \
--restart always \
-p 18789:18789 \
-v /opt/openclaw/config:/app/config \
-v /opt/openclaw/workspace:/app/workspace \
-v /opt/openclaw/skills:/app/skills \
openclaw/openclaw:2026.3.26

七、阿里云千问大模型 API 配置

1. 获取 API Key

访问登录阿里云百炼大模型服务平台 → 密钥管理 → 创建 API Key

2. 命令行一键配置

docker exec -it openclaw bash
openclaw config set models.providers.bailian.baseUrl https://dashscope.aliyuncs.com/compatible-mode/v1
openclaw config set models.providers.bailian.apiKey sk-你的密钥
openclaw config set models.default.model bailian/qwen3-max
openclaw gateway restart

八、免费大模型 Coding Plan API 配置

docker exec -it openclaw bash
nano /app/config/model.config.yaml

写入：

coding-plan:
  enable: true
  model: coding-free
  api_key: 你的免费API Key
  baseUrl: https://api.codingplan.ai/v1
  timeout: 30

重启：

openclaw gateway restart

九、最常用启动、检查、修复命令

# 检查配置是否合法（最关键）
openclaw doctor

# 自动修复配置错误
openclaw doctor --fix

# 查看网关状态
openclaw gateway status

# 重启网关
openclaw gateway restart

# 实时看日志（排查报错）
openclaw logs --follow

# 查看模型连接是否正常
openclaw model test

# 查看渠道连接状态
openclaw channels status

十、新手高频报错 10 种 100% 解决

1. Gateway 启动失败

原因：JSON 格式错 / 未知字段 / 层级错误
解决

openclaw doctor --fix

2. 模型调用失败

原因：apiKey 错 / baseUrl 错 / 无额度
解决：核对 Key，重启网关

3. 渠道@机器人无反应

原因：dmPolicy/groupPolicy 拦截 / 未配对 / 未重启
解决

openclaw pairing approve 渠道名 配对码
openclaw gateway restart

4. 无法访问面板 http://IP:18789

原因：端口没放行 / 容器没运行
解决

firewall-cmd --add-port=18789/tcp --permanent
firewall-cmd --reload
docker start openclaw

5. 配置改了不生效

原因：没重启网关
解决

openclaw gateway restart

6. 多 Agent 消息路由不对

原因：bindings 匹配错误
解决：用 channel: * 绑定默认 Agent

7. 技能装了不能用

原因：没启用 / 没重载
解决

openclaw skills enable --all
openclaw skills reload

8. 定时任务不执行

原因：cron 表达式错误 / 未启用
解决：开启 enabled: true，检查时间语法

9. 提示“权限不足”

原因：目录权限 / 容器用户问题
解决

sudo chmod -R 777 ~/.openclaw

10. 重启后配置丢失

原因：未挂载数据卷 / 未设置自启
解决

docker update --restart=always openclaw

十一、避坑终极原则（新手背下来）

先 doctor 再启动，改完配置必测试
unknown field 直接删，不要乱加字段
渠道先关闭再改，改完再开启
模型优先填千问，Coding Plan 做备用
workspace 分开，多 Agent 互不干扰
端口 18789 必须放行
密钥不要泄露，尽量放在 env 或环境变量

十二、总结

这篇是真正能让你从零直接跑通 OpenClaw的终极配置手册：

一份稳定 openclaw.json 模板直接复制
阿里云 + 本地三平台一键部署
千问 + 免费 Coding Plan 双模型配置
10 大高频报错一键修复
所有命令可直接粘贴使用

只要按照本文配置，你的 OpenClaw Gateway 一定能稳稳启动，不再因为配置问题卡住。

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

Openclaw.json文件终极配置指南：Gateway稳定启动+阿里云/本地部署+千问/Coding Plan全配置