OpenClaw 实战：openclaw.json 的 14 个模块，我踩过的坑都在这了

折腾 OpenClaw 这段时间，配置文件是我花最多时间的地方。

一开始我以为就一个 JSON 文件，照着示例填填 API Key 就行。结果跑起来各种报错——模型不认、工具调用不了、飞书消息收不到、网关连不上……排查半天，最后发现是 JSON 格式错了、Key 引用方式不对、或者模块之间互相依赖搞混了。

这篇文章把我踩过的坑、踩过的雷、以及现在的稳定配置写法全列出来。纯实战经验，希望能帮你少走弯路。

配置文件长什么样？

在 ~/.openclaw/ 目录下有一个 openclaw.json，这就是 OpenClaw 的核心配置文件。它把所有配置拆成了 14 个模块，每个模块管一块。

先看整体结构，知道有什么：

├── auth          认证配置（API Key 等）├── models        模型配置（提供商、API 地址、模型列表）├── agents        智能体配置（默认模型、工作区、会话）├── tools         工具配置（启用/禁用哪些工具）├── channels      渠道配置（飞书、企业微信等）├── gateway       网关配置（端口、访问控制）├── session       会话配置（生命周期、超时）├── hooks         自动化配置（定时任务等）├── bindings      多路由配置（消息分流到不同 Agent）├── plugins       插件配置├── skills        技能配置├── env           环境变量（敏感信息存储）├── logging       日志配置├── messages      消息行为配置└── commands      斜杠命令配置

我的做法：不用一次把所有模块都配上。先配最关键的三个——auth、models、agents，先把 Agent 跑起来，再按需逐个添加其他模块。

1. auth 模块：API Key 怎么放最安全

这个模块管所有外部服务的 API Key 认证信息。

常见错误：直接在 JSON 里写明文 Key。

{  "auth": {    "profiles": {      "zai:default": {        "provider": "zai",        "mode": "api_key",        "apiKey": "${ZAI_API_KEY}"      }    }  }}

关键点：• provider 的值必须和 models 模块里的提供商名称完全一致，大小写都敏感• apiKey 用 ${ENV_VAR} 格式引用环境变量，不要写明文• 配置前先 export ZAI_API_KEY="sk-xxx" 设置好环境变量

我踩过的坑：provider 写成了 "zai:default"，结果模型调用一直报 401。后来发现 provider 名字应该是 "zai"，":default" 是 profile 名称的一部分，不能写进 provider 字段。

2. models 模块：最核心的配置

这个模块定义了系统能调用哪些模型、通过哪个 API 调用。

我的配置思路：每个提供商配一个 provider，里面列出我能用的模型列表。

智谱 AI 配置：

{  "models": {    "mode": "merge",    "providers": {      "zai": {        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",        "api": "openai-completions",        "models": [          {            "id": "glm-5",            "name": "GLM-5",            "contextWindow": 204800,            "maxTokens": 131072,            "reasoning":true          },          {            "id": "glm-4-flash",            "name": "GLM-4-Flash",            "contextWindow": 128000,            "maxTokens": 8192,            "reasoning":false          }        ]      }    }  }}

OpenRouter 配置：

{  "models": {    "mode": "merge",    "providers": {      "openrouter": {        "baseUrl": "https://openrouter.ai/api/v1",        "api": "openai-completions",        "models": [          {            "id": "google/gemini-2.0-flash",            "name": "Gemini 2.0 Flash",            "contextWindow": 1000000,            "maxTokens": 8192,            "reasoning":true          }        ]      }    }  }}

关键点：• mode: "merge" = 合并内置模型和自定义模型（我用这个）• id 必须是提供商那边的准确模型 ID，自己编的 ID 会报错• contextWindow 影响上下文长度，设小了会截断，设大浪费了也没用• reasoning: true = 启用推理能力，复杂任务建议开

我的坑：baseUrl 后面多了一个 /，导致所有模型调用都报 404。OpenAI 兼容接口的 URL 格式很讲究，末尾不能有多余斜杠。

3. agents 模块：Agent 的”大脑”配置

这个模块决定 Agent 用什么模型、工作区在哪、会话怎么管理。

我的配置：

{  "agents": {    "defaults": {      "model": {        "primary": "zai/glm-5",        "fallbacks": ["openrouter/google/gemini-2.0-flash"]      },      "workspace": "~/.openclaw/workspace",      "compaction": {        "mode": "safeguard"      },      "heartbeat": 300    }  }}

关键点：• primary 格式是 提供商/模型ID，必须和 models 模块里配的完全一致• fallbacks 是备用模型列表，主模型不可用时自动切• workspace 是 Agent 的工作目录，只能读写这个目录下的文件• heartbeat: 300 = 每 5 分钟检测 Agent 是否存活• compaction.mode: "safeguard" = 长对话自动压缩，防止超出上下文

我的坑：fallbacks 写成了字符串不是数组，导致 Agent 卡死不启动。JSON 里数组必须用 [] 包裹。

4. tools 模块：让 Agent 能用工具

控制 Agent 能做什么——搜索、执行命令、读写文件等。

全量配置：

{  "tools": {    "profile": "full",    "deny": [],    "allow": [],    "web": {      "search": {        "enabled":true      },      "timeout": 10    }  }}

保守配置（只保留基础工具）：

{  "tools": {    "profile": "basic",    "deny": ["browser", "canvas"],    "allow": [],    "web": {      "search": {        "enabled":true      }    }  }}

关键点：• profile: "full" = 启用全部工具；"basic" = 仅基础工具• deny 是禁用列表，allow 是白名单（allow 优先于 deny）• web.search.enabled: true = 启用网页搜索

5. channels 模块：连接飞书

飞书配置：

{  "channels": {    "feishu": {      "enabled":true,      "appId": "cli_axxxxxxxx",      "appSecret": "${FEISHU_APP_SECRET}",      "connectionMode": "websocket",      "streaming":true,      "timeout": 30    }  }}

企业微信配置：

{  "channels": {    "wecom": {      "enabled":true,      "corpId": "wwxxxxxxx",      "corpSecret": "${WECOM_CORP_SECRET}",      "agentId": 1000001,      "connectionMode": "websocket"    }  }}

关键点：• appId 是 cli_ 开头的字符串，不是纯数字• connectionMode: "websocket" = 长连接（推荐）• streaming: true = 消息流式输出

我的坑：appId 填错了，飞书机器人一直收不到消息。后来去飞书开发者平台重新看了下，cli_ 开头的字符串和后面的数字要完整复制，不能漏。

6. gateway 模块：网关安全

本地安全模式：

{  "gateway": {    "port": 18789,    "mode": "local",    "bind": "loopback",    "auth": {      "mode": "token",      "token": "${GATEWAY_TOKEN}"    },    "timeout": 60  }}

公网访问模式：

{  "gateway": {    "port": 18789,    "mode": "public",    "bind": "0.0.0.0",    "auth": {      "mode": "token",      "token": "${GATEWAY_TOKEN}"    }  }}

关键点：• bind: "loopback" = 仅本机可访问（安全）• bind: "0.0.0.0" = 所有地址可访问（公网模式，需配 token）• 修改此模块后需 openclaw gateway restart

7. session 模块：会话管理

{  "session": {    "ttl": 86400,    "timeout": 3600,    "autosave":true,    "autosaveInterval": 300  }}

• ttl: 86400 = 会话保留 24 小时• timeout: 3600 = 1 小时无活动自动结束• autosaveInterval: 300 = 每 5 分钟自动保存

8. hooks 模块：定时任务

{  "hooks": {    "cron": [      {        "id": "daily-report",        "schedule": "0 9 * * *",        "agent": "main",        "prompt": "生成今日AI资讯摘要，并发布到公众号草稿箱"      }    ]  }}

• schedule 是标准 cron 表达式：分 时 日 月 周• 0 9 * * * = 每天早上 9 点执行• agent 指定用哪个 Agent 执行（需要 bindings 配置过）

9. bindings 模块：多 Agent 路由

{  "bindings": {    "rules": [      {        "channel": "feishu",        "keyword": ["写代码", "debug", "编程"],        "agent": "coder"      },      {        "channel": "feishu",        "keyword": ["报告", "总结", "周报"],        "agent": "writer"      }    ]  }}

• 规则按顺序匹配，第一个命中的生效• 多租户场景用这个模块

10. env 模块：敏感信息存储

{  "env": {    "ZAI_API_KEY": "sk-xxxx",    "GATEWAY_TOKEN": "xxxx",    "FEISHU_APP_SECRET": "xxxx"  }}

我的做法：env 里存的是明文，所以我严格控制 openclaw.json 的文件权限——chmod 600 openclaw.json，只有我自己能读。

11. logging 模块：日志级别

{  "logging": {    "level": "info",    "path": "~/.openclaw/logs",    "maxSize": 100,    "maxDays": 7  }}

• "debug" = 最详细（排查问题时用）• "info" = 普通日志（日常用这个）• "error" = 仅记录错误

12. messages 模块：消息行为

{  "messages": {    "prefix": "[虾哥AI] ",    "format": "markdown",    "ack": {      "enabled":true,      "reaction": "✅"    }  }}

• prefix = 回复前缀，方便区分是 AI 的回复• ack.reaction = 飞书消息已读回执显示的表情

快速参考表

总结

折腾 OpenClaw 这段时间，我最大的感悟是：配置文件不是填完就完事了，它是个活的东西，会随着使用过程不断调整。

几个建议：• 先跑通再调优，别一开始就配全套• JSON 格式错了是最常见的问题，用在线 JSON 校验器过一遍• Key 引用方式一定要用 ${ENV_VAR}，别写明文• 改了 channels 和 gateway 后要重启网关

有什么踩坑经验，欢迎交流。