OpenClaw 配置手册|openclaw.json 完全指南

{  "name": "OpenClaw", // 字符串类型：服务名称  "version": "2026.3.13", // 字符串类型：OpenClaw 版本  "enabled": true, // 布尔值类型：是否启用该服务（true=启用，false=禁用）  "port": 18789, // 数字类型：监听端口  "features": ["agent", "tools", "plugins"] // 数组类型：启用的功能模块}

{  "meta": {},        // 版本信息（系统自动生成和维护，无需手动修改）  "wizard": {},      // 向导运行记录（初始化时自动生成，记录配置过程，无需修改）  "auth": {},        // 认证配置（存储模型提供商、平台的API Key等认证信息，重点）  "models": {},      // 模型提供商和默认模型配置（决定Agent用哪个模型运行，核心重点）  "agents": {},      // Agent 核心配置（工作区路径、默认模型、会话优化等，核心重点）  "tools": {},       // 工具配置（控制Agent可使用的工具，如网页搜索、命令执行，重点）  "commands": {},    // 斜杠命令配置（控制 /reset、/help 等命令的启用状态）  "session": {},     // 会话管理配置（会话生命周期、超时时间、重置规则等）  "hooks": {},       // 钩子配置（自动化触发器，如定时执行任务、事件触发操作）  "channels": {},    // 通道配置（对接飞书、企业微信等平台，重点）  "gateway": {},     // 网关设置（监听端口、访问权限、认证令牌等，核心重点）  "skills": {},      // 技能配置（可插拔技能，如搜索、日历、翻译等）  "plugins": {},     // 插件配置（扩展OpenClaw功能，如自定义工具、模板等）  "env": {},         // 环境变量配置（安全存储敏感信息，进阶配置）  "messages": {},    // 消息行为配置（回复前缀、消息队列、ACK反应等）  "bindings": {},    // 多Agent路由配置（一个网关管理多个Agent，团队适用）  "logging": {}      // 日志配置（日志级别、输出路径，方便排查故障）}

{  "meta": {    "lastTouchedVersion": "2026.3.13", // 最后修改的OpenClaw版本    "lastTouchedAt": "2026-03-18T14:11:59.484Z" // 最后修改时间（自动生成）  },  "auth": {    "profiles": {      "zai:default": {        "provider": "zai", // 模型提供商（这里是智谱AI）        "mode": "api_key" // 认证方式（api_key 方式，最常用）      },      "openrouter:default": {        "provider": "openrouter", // 另一模型提供商（OpenRouter）        "mode": "api_key" // 认证方式      }    }  },  "models": {    "mode": "merge", // 模型加载模式（merge=合并内置和自定义模型，默认推荐）    "providers": {      "zai": {        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4", // 智谱API地址（固定）        "api": "openai-completions", // API兼容类型（适配OpenAI格式）        "models": [{"id": "glm-5", "name": "GLM-5", "reasoning": true}] // 可用模型列表      }    }  },  "agents": {    "defaults": {      "model": {"primary": "zai/glm-5"}, // Agent默认使用的主模型（格式：提供商/模型ID）      "workspace": "~/.openclaw/workspace" // Agent工作区路径（存储会话、日志等，默认即可）    }  },  "channels": {    "feishu": {      "enabled": true, // 启用飞书渠道（true=启用，false=禁用）      "appId": "cli_xxxxxxxxxx", // 飞书开发者平台获取的App ID      "appSecret": "xxxxxxxxxxxxxxxxxxxxxx", // 飞书开发者平台获取的App Secret      "connectionMode": "websocket" // 连接方式（websocket=长连接，推荐，实时接收消息）    }  },  "gateway": {    "port": 18789, // 网关监听端口（默认18789，可修改，避免端口冲突）    "mode": "local", // 运行模式（local=本地运行，适合个人使用）    "bind": "loopback" // 访问权限（loopback=仅本机可访问，安全）  }}

{  "meta": {    "lastTouchedVersion": "2026.3.13", // 最后修改对应的OpenClaw版本    "lastTouchedAt": "2026-03-18T14:11:59.484Z" // 最后修改时间（UTC时间，自动生成）  }}

{  "auth": {    "profiles": {      // 智谱AI 认证配置（示例）      "zai:default": {"provider": "zai", "mode": "api_key", "apiKey": "${ZAI_API_KEY}"},      // OpenRouter 认证配置（示例）      "openrouter:default": {"provider": "openrouter", "mode": "api_key", "apiKey": "${OPENROUTER_API_KEY}"}    }  }}

{  "models": {    "mode": "merge", // 模型加载模式（merge=合并内置和自定义模型，默认推荐）    "providers": {      // 智谱AI 提供商配置（示例）      "zai": {        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4", // 智谱API地址（固定不变）        "api": "openai-completions", // API兼容类型（适配OpenAI格式，无需修改）        "models": [          {            "id": "glm-5", // 模型ID（唯一标识，引用时用「提供商/模型ID」，如 zai/glm-5）            "name": "GLM-5", // 模型名称（自定义，方便识别）            "contextWindow": 204800, // 上下文窗口大小（单位：token，越大支持长对话越强）            "maxTokens": 131072, // 单次最大输出token数（控制单次回复长度）            "reasoning": true // 是否启用推理能力（true=启用，推荐开启）          }        ]      }    }  }}

model.primary{  "agents": {    "defaults": {      "model": {        "primary": "zai/glm-5", // 主模型（格式：提供商/模型ID，必须与models字段中的模型ID一致）        "fallbacks": ["openrouter/xiaomi/mimo-v2-pro"] // 备用模型（主模型故障时自动切换）      },      "workspace": "~/.openclaw/workspace", // Agent工作区路径（存储会话、日志、临时文件等）      "compaction": {"mode": "safeguard"}, // 长对话优化模式（safeguard=安全模式，默认推荐）      "heartbeat": 300 // 心跳检测时间（单位：秒，300=5分钟，用于检测Agent运行状态）    }  }}

profile: "full"{  "tools": {    "profile": "full", // 工具预设模板（full=启用全部工具，新手推荐；basic=仅启用基础工具）    "deny": ["browser", "canvas"], // 禁止使用的工具名单（数组形式，填写工具ID）    "allow": [], // 允许使用的工具名单（优先级高于deny，空数组表示允许所有未被禁止的工具）    "web": {      "search": {"enabled": true}, // 启用网页搜索工具（true=启用，false=禁用）      "timeout": 10 // 网页搜索超时时间（单位：秒，默认10秒）    }  }}

{  "channels": {    "feishu": { // 渠道名称（飞书，固定为feishu）      "enabled": true, // 启用飞书渠道（true=启用，false=禁用）      "appId": "cli_xxxxxxxxxx", // 飞书开发者平台获取的App ID（必填）      "appSecret": "xxxxxxxxxxxxxxxxxxxxxx", // 飞书开发者平台获取的App Secret（必填）      "connectionMode": "websocket", // 连接方式（websocket=长连接，推荐；webhook=回调方式）      "streaming": true, // 消息流式输出（true=实时分段回复，false=一次性回复）      "timeout": 30 // 消息响应超时时间（单位：秒，默认30秒）    }  }}

{  "gateway": {    "port": 18789, // 网关监听端口（默认18789，可修改，需避免与其他服务端口冲突）    "mode": "local", // 运行模式（local=本地运行，public=公网可访问）    "bind": "loopback", // 绑定地址（loopback=仅本机可访问，0.0.0.0=所有地址可访问）    "auth": {      "mode": "token", // 认证方式（token=令牌认证，none=无认证）      "token": "${GATEWAY_TOKEN}" // 认证令牌（推荐用环境变量引用，避免明文）    },    "timeout": 60 // 网关请求超时时间（单位：秒，默认60秒）  }}

{  "env": {    // 直接定义环境变量（键名大写，值为敏感信息）    "ZAI_API_KEY": "xxxxx",    "OPENROUTER_API_KEY": "gsk-xxxxx",    // 批量定义环境变量（vars 是对象，可添加多个键值对）    "vars": {      "GATEWAY_TOKEN": "xxxxxxxxxxxx",      "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxxxx"    }  }}

{  "messages": {    "prefix": "[OpenClaw 回复] ", // 回复消息前缀（自定义，方便区分Agent回复）    "queue": {"enabled": true, "maxSize": 10}, // 消息队列（启用后可处理并发消息）    "ack": {"enabled": true, "reaction": "✅"}, // ACK反应（飞书消息已读回执，显示✅）    "format": "markdown" // 消息格式（markdown=富文本，plain=纯文本）  }}

{  "bindings": {    "rules": [      {        "channel": "feishu", // 匹配渠道（飞书）        "user": ["user1@feishu.com", "user2@feishu.com"], // 匹配用户        "agent": "agent1" // 路由到的Agent名称      },      {        "keyword": ["技术", "开发"], // 匹配消息关键词        "agent": "agent2" // 路由到的Agent名称      }    ]  }}

{  "logging": {    "level": "info", // 日志级别（debug=详细日志，info=普通日志，error=仅错误日志）    "path": "~/.openclaw/logs", // 日志输出路径（默认）    "maxSize": 100, // 单个日志文件最大大小（单位：MB，默认100MB）    "maxDays": 7 // 日志保留天数（默认7天，自动清理过期日志）  }}