Appearance
OpenClaw配置文件openclaw.json完整解析：14个模块详解，包括auth认证、models模型、agents智能体、channels飞书配置等，附带快速参考表。
文件结构：先搞清楚有哪些模块
~/.openclaw/openclaw.json 文件里有哪些顶层字段？
├── auth 认证配置（API Key等）
├── models 模型配置（提供商、API地址、模型列表）
├── agents 智能体配置（默认模型、工作区、会话）
├── tools 工具配置（启用/禁用哪些工具）
├── channels 渠道配置（飞书、企业微信等）
├── gateway 网关配置（端口、访问控制）
├── session 会话配置（生命周期、超时）
├── hooks 自动化配置（定时任务等）
├── bindings 多路由配置（消息分流到不同Agent）
├── plugins 插件配置
├── skills 技能配置
├── env 环境变量（敏感信息存储）
├── logging 日志配置
└── messages 消息行为配置auth模块：你的API Key存在这里
作用： 存储所有外部服务的API Key认证信息
json
{
"auth": {
"profiles": {
"zai:default": {
"provider": "zai",
"mode": "api_key",
"apiKey": "${ZAI_API_KEY}"
}
}
}
}关键点：
provider的值必须和models里的提供商名称对应apiKey务必使用${ENV_VAR}格式，不要明文填写
models模块：最核心的配置
作用： 定义可以用哪些模型，通过哪个API调用
json
{
"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
}
]
}
}
}
}关键点：
mode: "merge"= 合并内置模型和自定义模型id必须是模型提供商的准确IDcontextWindow单位是Token，影响上下文长度
agents模块：控制Agent的行为
json
{
"agents": {
"defaults": {
"model": {
"primary": "zai/glm-5",
"fallbacks": ["openrouter/google/gemini-2.0-flash"]
},
"workspace": "~/.openclaw/workspace",
"heartbeat": 300
}
}
}关键点：
primary的格式是提供商/模型IDfallbacks是备用模型列表heartbeat: 300= 每5分钟检测一次Agent是否存活
channels模块：连接飞书/企业微信
json
{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_axxxxxxxx",
"appSecret": "${FEISHU_APP_SECRET}",
"connectionMode": "websocket",
"streaming": true
}
}
}关键点：
appId是cli_开头的字符串connectionMode: "websocket"= 长连接（推荐）streaming: true= 消息流式输出
gateway模块：网关安全配置
json
{
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"auth": {
"mode": "token",
"token": "${GATEWAY_TOKEN}"
}
}
}关键点：
bind: "loopback"= 仅本机可访问（安全）bind: "0.0.0.0"= 所有地址可访问（需要配合token认证）
hooks模块：定时任务自动化
json
{
"hooks": {
"cron": [
{
"id": "daily-report",
"schedule": "0 9 * * *",
"agent": "main",
"prompt": "生成今日AI资讯摘要"
}
]
}
}关键点：
schedule使用标准cron表达式：分 时 日 月 周0 9 * * *= 每天早上9点执行
快速参考表
| 模块 | 常用场景 | 修改后需重启？ |
|---|---|---|
| auth | 换API Key | 否 |
| models | 添加/切换模型 | 否 |
| agents | 改默认模型 | 否 |
| tools | 禁用某个工具 | 否 |
| channels | 配置飞书 | 是 |
| gateway | 改端口/安全策略 | 是 |
| session | 改超时策略 | 否 |
| hooks | 设置定时任务 | 否 |
每个模块都配上直接能用的示例了。改哪个字段，对照着复制过去就行。
