OpenClaw openclaw.json 全字段配置详解,一篇讲清...

OpenClaw 配置文件 openclaw.json 全字段一次性讲清楚！

适用版本：OpenClaw 2026.3.11+ | 格式：JSON5（支持注释）| 配置文件：~/.openclaw/openclaw.json

一、agents — 模型选择、心跳、沙盒隔离

agents 模块是整个配置的"大脑"，控制 AI 的核心行为。

{  "agents": {    "defaults": {      // 模型选择      "model": {        "primary": "minimax-cn/MiniMax-M2.5",        "fallbacks": ["minimax-cn/MiniMax-M2.5-highspeed"]      },      "models": {        "minimax-cn/MiniMax-M2.5": { "alias": "主力" },        "minimax-cn/MiniMax-M2.5-highspeed": { "alias": "极速" }      },      "workspace": "~/.openclaw/workspace",      // 心跳检测      "heartbeat": {        "every": "30m",        "target": "last"      },      // 沙盒隔离      "sandbox": {        "mode": "non-main",        "scope": "agent",        "workspaceAccess": "none",        "docker": {          "image": "openclaw-sandbox:bookworm-slim",          "network": "none",          "memory": "1g",          "cpus": 1        }      }    }  }}

关键配置说明：

primary/fallbacks：主模型不可用时，自动切换到备用模型，支持多级降级

heartbeat.every：建议生产环境设为 "30m" 或 "1h"，可配合 HEARTBEAT.md 实现主动巡检

sandbox：开启后 AI 运行在 Docker 容器中，即使被提示注入攻击也影响有限，推荐生产环境开启

⚠️ sandbox.docker.network: "bridge" 会让容器访问外网，仅调试用，不要在生产环境开启

二、models — API密钥安全配置

models 模块定义所有可用的 AI 模型供应商，支持 OpenAI、Anthropic、Minimax、Moonshot 等任意兼容 API。

{  "models": {    "mode": "merge",    "providers": {      "minimax": {        "baseUrl": "https://api.minimax.io/anthropic",        "apiKey": "${MINIMAX_API_KEY}",        "api": "anthropic-messages",        "models": [          {            "id": "MiniMax-M2.5",            "contextWindow": 200000,            "maxTokens": 8192,            "cost": { "input": 15, "output": 60, "cacheRead": 2, "cacheWrite": 10 }          }        ]      },      "moonshot": {        "baseUrl": "https://api.moonshot.cn/v1",        "apiKey": "${MOONSHOT_API_KEY}",        "api": "openai-completions",        "models": [          { "id": "kimi-k2.5", "contextWindow": 256000, "maxTokens": 8192 }        ]      }    }  }}

关键配置说明：

mode：默认 merge，会叠加到 OpenClaw 内置模型目录；设 replace 则完全替换

baseUrl：API 基础地址，末尾不要加/v1，否则某些适配器会变成 /v1/v1 导致 404

api适配器类型可选：anthropic-messages（Anthropic系）、openai-completions（OpenAI兼容）、openai-responses、google-generative-ai

apiKey：强烈建议使用 ${ENV_VAR} 语法引用环境变量，而非硬编码明文密钥

models.*.alias：设置后可在对话中用 /model 主力快速切换

三、channels — 微信/Telegram/飞书三大渠道配置

channels 模块接入各种 IM 渠道，是 AI 对外服务的"窗口"。

3.1 飞书（Lark/Feishu）

{  "channels": {    "feishu": {      "enabled": true,      "groupPolicy": "open",      "connectionMode": "websocket",      "streaming": true,      "accounts": {        "default": {          "appId": "${FEISHU_APP_ID}",          "appSecret": "${FEISHU_APP_SECRET}",          "botName": "AI助手",          "dmPolicy": "open",          "allowFrom": ["*"],          "enabled": true        }      }    }  }}

3.2 Telegram

{  "channels": {    "telegram": {      "enabled": true,      "botToken": "${TELEGRAM_BOT_TOKEN}",      "dmPolicy": "pairing",      "allowFrom": ["tg:123456789"],      "groups": {        "*": { "requireMention": true }      }    }  }}

3.3 微信公众号（企微/微信）

{  "channels": {    "wecom": {      "enabled": true,      "accounts": {        "default": {          "corpId": "${WECOM_CORP_ID}",          "corpSecret": "${WECOM_CORP_SECRET}",          "agentId": "${WECOM_AGENT_ID}",          "dmPolicy": "allowlist",          "allowFrom": ["*"]        }      }    }  }}

通用配置说明：

dmPolicy四个选项：open（开放）、pairing（首次配对）、allowlist（白名单）、disabled（禁用）

allowFrom支持格式："*"（所有人）、飞书 "ou_xxx"、Telegram "tg:123456789"、Discord "1234567890"

groupPolicy：控制群聊消息是否响应，requireMention: true 表示必须 @ 机器人才回复

四、gateway — 端口、热重载、访问控制

gateway 模块控制 OpenClaw 网关服务的行为，是"基础设施层"。

{  "gateway": {    "port": 18789,    "mode": "local",    "bind": "loopback",    "controlUi": {      "enabled": true,      "basePath": "/openclaw",      "allowInsecureAuth": false,      "dangerouslyDisableDeviceAuth": false    },    "auth": {      "mode": "token",      "token": "${OPENCLAW_GATEWAY_TOKEN}"    },    "reload": {      "mode": "hybrid",      "debounceMs": 300    },    "tailscale": {      "mode": "off",      "resetOnExit": false    }  }}

关键配置说明：

bind: "lan"会暴露到局域网，生产环境务必设bind: "loopback"并通过 Tailscale 或 VPN 访问

controlUi.basePath：设为随机路径（如 /8n3eby）可防止端口扫描发现控制面板

auth.mode: "token"：配合 ${OPENCLAW_GATEWAY_TOKEN} 生成 64 位随机令牌，极大提升安全性热重载默认 hybrid 模式，大多数配置变更无需重启，网关自动感知

五、session — 会话隔离、自动重置策略

session 模块控制对话的上下文管理和生命周期。

{  "session": {    "dmScope": "per-account-channel-peer",    "reset": {      "mode": "daily",      "atHour": 4    },    "resetByType": {      "thread": { "mode": "daily", "atHour": 4 },      "direct": { "mode": "idle", "idleMinutes": 240 },      "group": { "mode": "idle", "idleMinutes": 120 }    },    "resetTriggers": ["/new", "/reset"],    "maintenance": {      "mode": "warn",      "pruneAfter": "30d",      "maxEntries": 500,      "rotateBytes": "10mb",      "maxDiskBytes": "500mb"    }  }}

会话隔离策略对比：

dmScope 值	适用场景	说明
`main`	个人单账号	所有私信共用一个会话
`per-peer`	个人多渠道	每个用户一个会话（跨渠道）
`per-channel-peer`	多渠道多用户	按渠道+用户隔离（推荐）
`per-account-channel-peer`	多机器人多用户	最严格隔离（本文配置方案）

六、tools — 联网搜索、Shell命令、权限控制

tools 模块是安全配置的核心，决定 AI 能做什么、不能做什么。

{  "tools": {    "profile": "full",    "deny": [      "browser",      "web_search",      "web_fetch"    ],    "byProvider": {      "feishu": { "profile": "messaging" },      "telegram": { "profile": "messaging" }    },    "elevated": {      "enabled": false,      "allowFrom": {}    },    "exec": {      "backgroundMs": 10000,      "timeoutSec": 1800,      "cleanupMs": 1800000    },    "loopDetection": {      "enabled": true,      "historySize": 30,      "warningThreshold": 10,      "criticalThreshold": 20,      "detectors": {        "genericRepeat": true,        "knownPollNoProgress": true,        "pingPong": true      }    }  }}

工具配置文件速查：

配置	包含工具	适用场景
`minimal`	仅 session_status	纯对话机器人
`messaging`	消息发送、会话查询	客服、通知
`coding`	文件读写、代码执行	编程助手
`full`	无限制	信任环境

七、cron/hooks — 定时任务、外部触发

cron 和 hooks 模块实现自动化，是"双手"。

7.1 定时任务（cron）

{  "cron": {    "enabled": true,    "maxConcurrentRuns": 2,    "sessionRetention": "24h",    "runLog": {      "maxBytes": "2mb",      "keepLines": 2000    }  }}

cron 任务通过 HEARTBEAT.md 或 OpenClaw CLI 创建，常用场景：定时播报新闻、定期巡检、定期发送报告。

7.2 Webhooks（hooks）

{  "hooks": {    "enabled": true,    "token": "${HOOKS_SHARED_SECRET}",    "path": "/hooks",    "defaultSessionKey": "hook:ingress",    "allowRequestSessionKey": false,    "allowedSessionKeyPrefixes": ["hook:"],    "mappings": [      { "match": { "path": "gmail" }, "action": "agent", "agentId": "main", "deliver": true },      { "match": { "path": "slack" }, "action": "agent", "agentId": "main" }    ]  }}

八、env — 环境变量、密钥安全存储

env 模块集中管理所有密钥和环境配置。

{  "env": {    "vars": {      "MINIMAX_API_KEY": "sk-or-...",      "FEISHU_APP_ID": "cli_xxx",      "FEISHU_APP_SECRET": "xxx",      "OPENCLAW_GATEWAY_TOKEN": "ab9113bbd086fff47f..."    },    "secrets": {      "providers": {        "env": { "source": "env" },        "file": { "source": "file", "path": "/root/.openclaw/.secrets" },        "exec": { "source": "exec", "cmd": "pass openclaw/api-key" }      }    },    "shellEnv": {      "enabled": true,      "timeoutMs": 15000    }  }}

密钥安全最佳实践：

生产环境所有 apiKey、token、secret一律使用${ENV_VAR}引用，不要硬编码在 JSON 中可以创建 ~/.openclaw/.env 文件集中存储密钥，OpenClaw 会自动加载支持 ${VAR:-default} 语法设置默认值：

"apiKey": "${MINIMAX_API_KEY:-sk-default}"

配合 secrets.providers.file 可使用 Vault、pass 等密钥管理工具

新手快速上手：三块配置搞定一切

最小可用配置（飞书）只需三块：

{  // ✅ 第一块：AI 模型  "models": {    "mode": "merge",    "providers": {      "minimax": {        "baseUrl": "https://api.minimax.io/anthropic",        "apiKey": "${MINIMAX_API_KEY}",        "api": "anthropic-messages",        "models": [{ "id": "MiniMax-M2.5", "contextWindow": 200000 }]      }    }  },  // ✅ 第二块：飞书渠道接入  "channels": {    "feishu": {      "enabled": true,      "accounts": {        "default": {          "appId": "${FEISHU_APP_ID}",          "appSecret": "${FEISHU_APP_SECRET}",          "dmPolicy": "open",          "allowFrom": ["*"]        }      }    }  },  // ✅ 第三块：智能体默认行为  "agents": {    "defaults": {      "model": { "primary": "minimax/MiniMax-M2.5" },      "workspace": "~/.openclaw/workspace"    }  }}

复制以上配置到 ~/.openclaw/openclaw.json，填入三个 env 变量，运行 openclaw gateway start，一个可用的 AI 对话机器人就上线了。

JSON5 注释技巧：让配置自文档化

JSON5 支持注释，让配置像代码一样可读：

{  // ========== 认证配置 ==========  "auth": {    "profiles": {      "minimax-cn:default": {        "provider": "minimax-cn",        "mode": "api_key"  // api_key=密钥认证 oauth=第三方登录      }    }  },  // 多行注释用多个单行注释模拟  // agents.defaults.model 控制默认使用的 AI 模型  // 如果需要多模型，可以在 models.providers 中添加更多供应商  "agents": {    "defaults": {      "model": {        "primary": "minimax/MiniMax-M2.5",        "fallbacks": ["minimax/MiniMax-M2.5-highspeed"]  // 模型降级兜底      }    }  },  // 重要提醒用大写注释块标记  // ⚠️ 注意：groupPolicy: "open" 允许所有群聊消息，测试后改为 allowlist  // ⚠️ 注意：sandbox.docker.network 不要设为 bridge，有安全风险  "channels": {    "feishu": {      "groupPolicy": "allowlist"  // TODO: 上线后改为 allowlist    }  }}

doctor 自动诊断命令

配置出问题？别慌，一行命令自动诊断：

# 基础诊断openclaw doctor# 自动修复（慎用，会修改配置）openclaw doctor --fix# 自动修复并确认（安全模式）openclaw doctor --yes

doctor 会检查的内容：

✅ JSON5 语法是否正确

✅ 字段类型是否匹配 schema

✅ 缺失的必需字段

✅ API 密钥格式是否有效

✅ 渠道配置是否完整

✅ 端口是否被占用

✅ 插件依赖是否满足

其他常用 CLI 命令：

# 查看当前配置（脱敏后）openclaw config show# 获取单个字段值openclaw config get agents.defaults.model# 设置字段值openclaw config set agents.defaults.heartbeat.every "1h"# 删除字段openclaw config unset tools.elevated.enabled# 重启网关openclaw gateway restart# 查看日志openclaw logs

完整配置模板

{  // ===== 元数据（系统自动管理）=====  "meta": {    "lastTouchedVersion": "2026.3.11",    "lastTouchedAt": "2026-03-29T00:00:00.000Z"  },  // ===== ① agents：智能体核心配置 =====  "agents": {    "defaults": {      "model": {        "primary": "minimax-cn/MiniMax-M2.5",        "fallbacks": ["minimax-cn/MiniMax-M2.5-highspeed"]      },      "models": {        "minimax-cn/MiniMax-M2.5": { "alias": "主力" },        "minimax-cn/MiniMax-M2.5-highspeed": { "alias": "极速" }      },      "workspace": "~/.openclaw/workspace",      "compaction": { "mode": "safeguard" },      "heartbeat": { "every": "30m", "target": "last" },      "sandbox": {        "mode": "non-main",        "scope": "agent",        "workspaceAccess": "none",        "docker": { "image": "openclaw-sandbox:bookworm-slim", "network": "none" }      }    }  },  // ===== ② models：AI 模型供应商 =====  "models": {    "mode": "merge",    "providers": {      "minimax": {        "baseUrl": "https://api.minimax.io/anthropic",        "apiKey": "${MINIMAX_API_KEY}",        "api": "anthropic-messages",        "models": [          { "id": "MiniMax-M2.5", "contextWindow": 200000, "maxTokens": 8192 }        ]      }    }  },  // ===== ③ channels：消息渠道 =====  "channels": {    "defaults": { "groupPolicy": "allowlist" },    "feishu": {      "enabled": true,      "groupPolicy": "open",      "connectionMode": "websocket",      "streaming": true,      "accounts": {        "default": {          "appId": "${FEISHU_APP_ID}",          "appSecret": "${FEISHU_APP_SECRET}",          "botName": "AI助手",          "dmPolicy": "open",          "allowFrom": ["*"],          "enabled": true        }      }    },    "telegram": {      "enabled": false,      "botToken": "${TELEGRAM_BOT_TOKEN}",      "dmPolicy": "pairing",      "allowFrom": [],      "groups": { "*": { "requireMention": true } }    }  },  // ===== ④ bindings：多智能体路由 =====  "bindings": [    { "agentId": "main", "match": { "channel": "feishu", "accountId": "default" } }  ],  // ===== ⑤ tools：工具权限控制 =====  "tools": {    "profile": "full",    "deny": ["browser", "web_search", "web_fetch"],    "elevated": { "enabled": false, "allowFrom": {} },    "loopDetection": { "enabled": false }  },  // ===== ⑥ session：会话管理 =====  "session": {    "dmScope": "per-account-channel-peer",    "reset": { "mode": "daily", "atHour": 4 },    "resetByType": {      "thread": { "mode": "daily", "atHour": 4 },      "direct": { "mode": "idle", "idleMinutes": 240 },      "group": { "mode": "idle", "idleMinutes": 120 }    },    "maintenance": { "mode": "warn", "pruneAfter": "30d", "maxEntries": 500 }  },  // ===== ⑦ gateway：网关配置 =====  "gateway": {    "port": 18789,    "mode": "local",    "bind": "loopback",    "controlUi": {      "enabled": true,      "basePath": "/openclaw",      "allowInsecureAuth": false,      "dangerouslyDisableDeviceAuth": false    },    "auth": { "mode": "token", "token": "${OPENCLAW_GATEWAY_TOKEN}" },    "reload": { "mode": "hybrid", "debounceMs": 300 },    "tailscale": { "mode": "off" }  },  // ===== ⑧ env：环境变量与密钥 =====  "env": {    "vars": {      "MINIMAX_API_KEY": "sk-or-...",      "FEISHU_APP_ID": "cli_xxx",      "FEISHU_APP_SECRET": "xxx",      "OPENCLAW_GATEWAY_TOKEN": "your-random-64-char-token"    }  }}

本文基于 OpenClaw 2026.3.11 编写。配置字段以官方 schema 为准，不同版本可能略有差异。建议收藏本文并配合 openclaw doctor 验证配置。

收藏了！这6个AI网址我用了一年还在用

神仙网址合集君 · 专注效率工具分享

关注公众号，获取更多技术干货与效率神器推荐

点在看是对我最大的支持 ❤️