夜雨聆风OpenClaw配置完全指南：openclaw.json详解
这篇文章把OpenClaw配置文件openclaw.json拆成模块来讲，结合示例说明每一个配置的作用。
一、文件结构：先搞清楚有哪些模块
~/.openclaw/openclaw.json 文件里有哪些顶层字段？
├── auth 认证配置（API Key等）
├── models 模型配置（提供商、API地址、模型列表）
├── agents 智能体配置（默认模型、工作区、会话）
├── tools 工具配置（启用/禁用哪些工具）
├── channels 渠道配置（飞书、企业微信等）
├── gateway 网关配置（端口、访问控制）
├── session 会话配置（生命周期、超时）
├── hooks 自动化配置（定时任务等）
├── bindings 多路由配置（消息分流到不同Agent）
├── plugins 插件配置
├── skills 技能配置
├── env 环境变量（敏感信息存储）
├── logging 日志配置
├── messages 消息行为配置
└── commands 斜杠命令配置按使用频率排序，常用的我会详细讲，不常用的简单带过。
二、auth模块：你的API Key存在这里
作用： 存储所有外部服务的API Key认证信息
示例：
{
"auth": {
"profiles": {
"zai:default": {
"provider": "zai",
"mode": "api_key",
"apiKey": "${ZAI_API_KEY}"
},
"openrouter:default": {
"provider": "openrouter",
"mode": "api_key",
"apiKey": "${OPENROUTER_API_KEY}"
}
}
}
}关键点：
provider的值必须和 models 里的提供商名称对应apiKey务必使用${ENV_VAR}格式，不要明文填写- 先设置环境变量：
export ZAI_API_KEY="你的Key"
三、models模块：最核心的配置
作用： 定义可以用哪些模型，通过哪个API调用
示例（智谱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
},
{
"id": "anthropic/claude-sonnet-4-5",
"name": "Claude Sonnet 4.5",
"contextWindow": 200000,
"maxTokens": 8192,
"reasoning": true
}
]
}
}
}
}关键点：
mode: "merge"= 合并内置模型和自定义模型（通常选这个）id必须是模型提供商的准确ID，不能自己编contextWindow单位是Token，影响上下文长度reasoning: true= 启用推理能力（复杂任务建议开启）
四、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的工作目录，Agent只能读写这个目录下的文件heartbeat: 300= 每5分钟检测一次Agent是否存活compaction.mode: "safeguard"= 长对话自动压缩，防止超出上下文限制
五、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"= 启用全部工具profile: "basic"= 仅启用基础工具（exec, read, write等）deny是禁用列表，allow是白名单（allow优先于deny）web.search.enabled: true= 启用网页搜索
六、channels模块：连接飞书/企业微信
作用： 让Agent能接收和回复飞书消息
飞书配置示例：
{
"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= 消息流式输出，边生成边显示- 务必在飞书开发者平台开启机器人和相关权限
七、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认证）- 修改port后需确保端口不被占用：
lsof -i :18789 - 修改此模块后需重启网关：
openclaw gateway restart
八、session模块：会话管理
作用： 控制会话的生命周期、超时、自动重置规则
示例：
{
"session": {
"ttl": 86400,
"timeout": 3600,
"autosave": true,
"autosaveInterval": 300
}
}关键点：
ttl: 86400= 会话保留24小时（单位：秒）timeout: 3600= 1小时内无活动自动结束会话autosaveInterval: 300= 每5分钟自动保存会话状态
九、hooks模块：定时任务自动化
作用： 设置定时任务，让Agent在特定时间自动执行
示例：
{
"hooks": {
"cron": [
{
"id": "daily-report",
"schedule": "0 9 * * *",
"agent": "main",
"prompt": "生成今日AI资讯摘要，并发布到公众号草稿箱"
}
]
}
}关键点：
schedule使用标准cron表达式：分 时 日 月 周0 9 *= 每天早上9点执行agent指定用哪个Agent执行（需要bindings里配置过）
十、bindings模块：多Agent路由
作用： 把不同用户/关键词路由到不同的Agent
示例：
{
"bindings": {
"rules": [
{
"channel": "feishu",
"user": ["user1@company.com"],
"agent": "coder"
},
{
"channel": "feishu",
"keyword": ["写代码", "debug", "编程"],
"agent": "coder"
},
{
"channel": "feishu",
"keyword": ["报告", "总结", "周报"],
"agent": "writer"
}
]
}
}关键点：
- 规则按顺序匹配，第一个命中的生效
user= 匹配特定用户keyword= 匹配消息关键词- 多租户场景使用这个模块
十一、env模块：安全存储敏感信息
作用： 在配置文件里安全存储环境变量，不暴露明文
示例：
{
"env": {
"ZAI_API_KEY": "sk-xxxx",
"OPENROUTER_API_KEY": "sk-xxxx",
"GATEWAY_TOKEN": "xxxx",
"FEISHU_APP_SECRET": "xxxx"
}
}关键点：
- env里的值是明文存储的，文件权限要控制好（
chmod 600 openclaw.json） - 更好的做法：只在env里放标记，实际Key通过shell环境变量传入
- 建议通过
${ENV_VAR}引用，而不是直接写值
十二、logging模块：日志配置
作用： 控制日志输出级别和保留策略
示例：
{
"logging": {
"level": "info",
"path": "~/.openclaw/logs",
"maxSize": 100,
"maxDays": 7
}
}关键点：
level: "debug"= 最详细（排查问题时用）level: "info"= 普通日志（日常运行选这个）level: "error"= 仅记录错误maxSize: 100= 单个日志文件最大100MBmaxDays: 7= 保留7天后自动清理
十三、messages模块：消息行为配置
作用： 控制Agent回复的格式、前缀、ACK反应等
示例：
{
"messages": {
"prefix": "[虾哥AI] ",
"format": "markdown",
"ack": {
"enabled": true,
"reaction": "✅"
}
}
}关键点：
prefix= 回复前缀，方便区分是AI的回复format: "markdown"= 支持富文本格式ack.reaction= 飞书消息已读回执显示的表情
十四、快速参考表
| 模块 | 常用场景 | 修改后需重启？ |
|---|---|---|
| auth | 换API Key | 否 |
| models | 添加/切换模型 | 否 |
| agents | 改默认模型 | 否 |
| tools | 禁用某个工具 | 否 |
| channels | 配置飞书 | 是 |
| gateway | 改端口/安全策略 | 是 |
| session | 改超时策略 | 否 |
| hooks | 设置定时任务 | 否 |
| bindings | 多租户路由 | 否 |
| env | 敏感信息存储 | 否 |
| logging | 改日志级别 | 否 |
| messages | 改回复格式 | 否 |
结尾
每个模块都配上直接能用的示例了。
改哪个字段，对照着复制过去就行。
有报错就对照上面的常见错误清单排查，十有八九是JSON格式或Key引用的问题。
欢迎在评论区聊聊你的配置经验~
如果这篇文章让你有收获，别忘了点赞、在看、转发三连～
也欢迎关注我的公众号，每天有AI最新资讯分享🦐
