openclaw.json on openclaw

agent

Mon, 01 Jan 0001 00:00:00 +0000

3 核心模块详解 3.1 agents - 代理默认配置 agents 模块定义了 AI 代理的默认行为，包括模型选择、并发控制等。简单说，就是告诉你的 AI 助手该怎么干活：

{ “agents”: { “defaults”: { “model”: { “primary”: “bailian/qwen3.5-plus”, “fallbacks”: [“bailian/qwen3-max”] }, “maxConcurrent”: 4, “subagents”: { “maxConcurrent”: 8 }, “workspace”: “C:\Users\xxx\.openclaw\workspace” } } } 关键字段说明：

primary

主用模型，日常对话默认使用（正宫娘娘） fallbacks
备用模型列表，主模型失败时自动切换（备胎团） maxConcurrent
最大并发请求数，避免 API 限流（别太贪心） workspace
工作区路径，存放记忆和技能文件（AI 的家） 💡 建议根据 API 提供商的限流策略调整并发数，百炼/Qwen 系列一般 4-8 比较安全。设太高容易被 API 方"请喝茶"。

4 高频修改场景 4.1 切换模型提供商想从百炼切换到 MiniMax？修改 agents.defaults.model：

“agents”: { “defaults”: { “model”: { “primary”: “minimax/MiniMax-M2.5-highspeed”, “fallbacks”: [“bailian/qwen3-max”] } } } 💡 确保目标模型已在 models.providers 中正确配置，否则会报错。别玩"无中生有"！

hooks

Mon, 01 Jan 0001 00:00:00 +0000

3.7 hooks - 钩子自动化 hooks 提供事件驱动的自动化能力，响应命令和生命周期事件。这里是你的"自动化流水线"：

{ “hooks”: { “internal”: { “enabled”: true, “entries”: { “boot-md”: {“enabled”: true}, “command-logger”: {“enabled”: true}, “session-memory”: {“enabled”: true} } } } } 内置钩子说明：

boot-md

Gateway 启动时执行 BOOT.md 指令（开机自启脚本） command-logger
记录所有命令到审计日志（留痕，懂的都懂） session-memory
/new 命令时保存会话上下文（记忆保鲜）

钩子管理命令

openclaw hooks list openclaw hooks enable session-memory openclaw hooks disable command-logger hooks.internal.enabled 枚举值详解：

枚举值说明 true 启用内部钩子系统 false 禁用所有内部钩子

plugins

Mon, 01 Jan 0001 00:00:00 +0000

3.6 plugins - 插件系统 plugins 模块管理插件的加载和启用。这里是你的"扩展商店"：

{ “plugins”: { “entries”: { “feishu”: {“enabled”: true} }, “load”: { “paths”: [ “C:\Users\xxx\AppData\Roaming\npm\node_modules\openclaw-cn\extensions\feishu” ] } } } 插件管理命令：

列出已安装插件

openclaw plugins list

安装新插件

openclaw plugins install @clawdbot/voice-call

启用/禁用插件

openclaw plugins enable voice-call openclaw plugins disable voice-call 💡 插件安装后需要重启 Gateway 才能生效，修改 entries 配置同样需要重启。别问为什么没反应，问就是没重启！

4.4 启用/禁用插件临时禁用某个插件而不删除配置：

“plugins”: { “entries”: { “voice-call”: {“enabled”: false}, “feishu”: {“enabled”: true} } } 或者使用 CLI 命令快速切换，无需手动编辑文件。懒人必备！

skills

Mon, 01 Jan 0001 00:00:00 +0000

3.8 skills - 技能管理 skills 模块配置技能的启用和 API 密钥。这里是 AI 的"技能树"：

{ “skills”: { “entries”: { “tavily”: { “apiKey”: “tvly-dev-xxx”, “enabled”: true } }, “install”: { “nodeManager”: “npm” } } } 技能相关：

entries

已安装技能的配置和开关（技能栏） install.nodeManager
包管理器选择（npm/pnpm/yarn） nodeManager 枚举值详解：

枚举值说明特点 npm 使用 npm 包管理器 Node.js 默认，最常用 pnpm 使用 pnpm 包管理器节省磁盘空间，速度快 yarn 使用 yarn 包管理器 Facebook 出品，稳定可靠 💡 部分技能需要独立的 API 密钥（如 tavily 搜索），需在 entries 中配置。别指望技能自己变出来！

常见错误与排查

Mon, 01 Jan 0001 00:00:00 +0000

5 5.1 配置格式错误症状：Gateway 启动失败，报错 JSON 解析错误

原因：

JSON 语法错误（缺少逗号、引号不匹配）使用了 JSON 不支持的注释尾部逗号（最后一个元素后多了一个逗号）解决：使用 JSON 验证工具检查，如 VS Code 的 JSON 插件或在线验证器。手滑是人之常情，验证器能救命！

5.2 重启不生效症状：修改配置后重启 Gateway，但行为未改变

排查步骤：

确认修改的是正确的配置文件（检查 OPENCLAW_CONFIG_PATH）确认 Gateway 已完全重启（不是热重载）检查配置层级是否正确（缩进、嵌套）查看 Gateway 日志确认配置加载成功

查看 Gateway 日志

tail -f ~/.openclaw/gateway.log 💡 90% 的"配置不生效"问题，都是因为你改错了文件或者没重启。别不好意思承认！

5.3 敏感信息泄露风险风险场景：

配置文件提交到 Git 仓库（公开处刑）截图分享时未打码 API 密钥（社死现场）日志文件包含完整配置（无意泄密）防护建议：

将 ~/.openclaw/ 加入 .gitignore（基本操作）使用 .env 文件存储敏感信息（安全习惯）定期轮换 API 密钥（亡羊补牢）

5.4 环境变量优先级症状：配置了 API Key 但未被使用

最佳实践建议

Mon, 01 Jan 0001 00:00:00 +0000

6 最佳实践建议 6.1 配置备份策略修改配置前先备份，这是血泪教训换来的经验：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d) 或者使用版本控制管理配置变更（敏感信息除外）：

cd ~/.openclaw git init git add openclaw.json git commit -m “Initial config” 💡 备份文件名加上日期，方便追溯历史版本。别等到改崩了才后悔！

6.2 测试验证流程修改配置后的标准验证流程，按部就班不出错：

JSON 语法验证（VS Code 或在线工具）重启 Gateway 检查日志无报错执行简单命令验证功能观察 5-10 分钟确认稳定别跳过任何一步，每一步都是在给你自己省时间！

6.3 安全配置原则最小权限原则：

仅启用必要的渠道和插件（够用就好）远程访问时启用 token 认证（别裸奔）使用 allowFrom 限制授权用户（白名单最安全） “channels”: { “whatsapp”: { “allowFrom”: ["+8613800138000"], “groups”: {"*": {“requireMention”: true}} } } ⚠️ 安全无小事，配置需谨慎。别等出事了才想起来看这篇文章！

auth

Mon, 01 Jan 0001 00:00:00 +0000

3.2 auth - 认证管理 auth 模块管理认证配置文件，决定使用哪些凭据访问服务。相当于你的"通行证管理中心"：

{ “auth”: { “order”: { “dashscope”: [“dashscope:default”] }, “profiles”: { “dashscope:default”: { “mode”: “api_key”, “provider”: “dashscope” } } } } 配置要点：

order

定义认证配置的优先级顺序（谁先谁后） profiles
具体认证配置文件，包含 provider 和 mode mode
认证模式，常见有 api_key 和 oauth mode 枚举值详解：

枚举值说明适用场景 api_key 使用 API 密钥认证大多数云服务，简单直接 oauth 使用 OAuth 授权需要用户授权的场景，如 Google、GitHub device_code 设备码认证无浏览器环境，如电视、终端设备 ⚠️ 敏感信息（如 API Key）建议放在 .env 文件中，通过 ${VAR_NAME} 引用，避免直接写入配置文件。别当"明文党"！

channels

Mon, 01 Jan 0001 00:00:00 +0000

3.5 channels - 渠道接入 channels 配置消息渠道，支持 WhatsApp、Telegram、Discord、飞书等。这里是你的"通讯兵营"：

{ “channels”: { “feishu”: { “accounts”: { “default”: { “appId”: “cli_xxx”, “appSecret”: “xxx”, “domain”: “feishu”, “enabled”: true } } } } } 多渠道配置示例：

需要扫描二维码配对（像加微信） Telegram
通过 BotFather 创建 Bot 获取 Token（认个干儿子） Discord
创建应用并邀请到服务器（进群要门票）飞书
创建企业自建应用获取 AppID/Secret（企业版通行证） enabled 枚举值详解：

枚举值说明 true 启用该渠道 false 禁用该渠道（配置保留但不生效） ⚠️ 每个渠道的认证信息不同，务必参考官方文档正确配置。别想一套配置走天下！

4.2 添加新的渠道想接入 Telegram？在 channels 下添加：

“channels”: { “telegram”: { “accounts”: { “default”: { “botToken”: “123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11”, “enabled”: true } } } } 然后通过 BotFather 创建 Bot，将 Token 填入配置即可。记得重启 Gateway！

gateway

Mon, 01 Jan 0001 00:00:00 +0000

3.3 gateway - 网关核心 gateway 是 OpenClaw 的心脏，控制网络绑定、端口和认证。说它是"总指挥部"也不为过：

{ “gateway”: { “auth”: { “mode”: “token”, “token”: “test_value” }, “bind”: “loopback”, “mode”: “local”, “port”: 18789, “tailscale”: { “mode”: “off”, “resetOnExit”: false } } } 核心参数：

bind

绑定地址，决定谁能访问 Gateway port
Gateway 服务端口，默认 18789（别随便改，容易忘） mode
运行模式，本地还是远程 tailscale
Tailscale 组网配置，用于安全远程访问 bind 枚举值详解：

枚举值说明安全性 loopback 仅本地访问（127.0.0.1） ⭐⭐⭐⭐⭐ 最安全 tailnet 允许 Tailscale 网络访问 ⭐⭐⭐⭐ 较安全 all 允许所有网络接口访问 ⭐⭐ 危险，慎用！ gateway.mode 枚举值详解：

枚举值说明适用场景 local 本地模式，仅本机使用个人开发、测试 remote 远程模式，允许外部访问团队协作、生产环境 tailscale.mode 枚举值详解：

gateway

Mon, 01 Jan 0001 00:00:00 +0000

3.4 models - 模型配置 models 模块定义可用的 AI 模型提供商和具体模型。这里是你的"AI 军火库"：

{ “models”: { “mode”: “merge”, “providers”: { “bailian”: { “api”: “openai-completions”, “apiKey”: “sk-sp-xxx”, “baseUrl”: “https://coding.dashscope.aliyuncs.com/v1", “models”: [ {“id”: “qwen3.5-plus”, “name”: “qwen3.5-plus”}, {“id”: “qwen3-max”, “name”: “qwen3-max”} ] }, “minimax”: { “api”: “openai-completions”, “apiKey”: “sk-api-xxx”, “baseUrl”: “https://api.minimaxi.com/v1", “models”: [ { “id”: “MiniMax-M2.5-highspeed”, “name”: “MiniMax-M2.5-highspeed”, “contextWindow”: 200000, “cost”: {“input”: 0.001, “output”: 0.004} } ] } } } } 配置说明：

api

API 兼容模式，openai-completions 最常用（万能钥匙） baseUrl
API 端点地址（门牌号） contextWindow
上下文窗口大小（token 数，越大越能聊） cost
计费标准，输入/输出每 token 价格（美元，钱包在滴血） models.mode 枚举值详解：

枚举值说明效果 merge 合并模式将配置与默认模型列表合并 override 覆盖模式完全替换默认模型列表 none 不加载不使用此配置 api 枚举值详解：