OpenClaw 配置文件保姆级解析：24 个顶层字段全拆解，新手也能轻松改
部署好 OpenClaw（小龙虾），却被密密麻麻的 openclaw.json 配置文件难住？切换模型、对接飞书、排查故障时，不知道该改哪个字段、怎么改，生怕一动就搞崩整个服务？
这份基于 2026.3.13 最新版本的配置文件全解析，～/.openclaw/openclaw.json 里 24 个顶层字段的含义、用法、实用示例讲透，每个核心字段都配可直接复制的代码片段 + 详细注释，还有配套表格辅助理解，从 JSON 基础语法到进阶配置，一步到位解决 OpenClaw 配置难的问题，新手也能上手就用！
回到正题~
先避坑：掌握 JSON 基础语法，躲开 90% 配置错误
OpenClaw 的核心配置都集中在 openclaw.json 中，本质是标准 JSON 文件，很多配置出错并非不懂字段，而是忽略了语法规范，记住 3 个核心规则，轻松避开大部分坑：
- 键值对结构：严格遵循"key": value格式，键名必须用双引号，冒号后加空格区分键值；
- 数据类型：支持 5 种常用类型 —— 字符串（双引号包裹）、数字（直接写）、布尔值（true/false 小写无引号）、数组（[] 包裹，元素逗号分隔）、对象（{} 包裹，内部键值对）；
- 格式规范：多元素间用逗号分隔，最后一个元素严禁加逗号，缩进建议 2 个空格，适配多端显示。
快速参考：JSON 常用数据类型说明
|
|
|
|
|
|---|---|---|---|
|
|
|
"baseUrl": "https://xxx" |
|
|
|
|
"port": 18789 |
|
|
|
|
"enabled": true |
|
|
|
|
"models": ["glm-5", "mimo-v2"] |
|
|
|
|
"auth": {"mode": "api_key"} |
|
基础认知：openclaw.json 核心字段总览
完成openclaw onboard初始化后，配置文件会自动生成基础结构，核心字段各有分工，不用盲目翻找，快速对应即可：
{"meta": {}, // 版本信息，系统自动维护"auth": {}, // 认证配置，存储API Key等敏感信息"models": {}, // 模型配置，决定Agent使用的模型，核心重点"agents": {}, // Agent配置，控制工作区、默认模型等，核心重点"tools": {}, // 工具配置，控制Agent可使用的工具"channels": {}, // 渠道配置，对接飞书、企业微信等平台"gateway": {}, // 网关配置，监听端口、访问权限等，核心重点"session": {}, // 会话管理，超时时间、重置规则等"hooks": {}, // 钩子配置，定时任务、事件触发器"logging": {} // 日志配置，排查故障必备}
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
核心重点：13 个常用字段详细解析（附可复制示例）
这部分是日常配置的核心，每个字段都包含说明 + 代码示例 + 注意事项，注释完整，直接复制替换即可，新手重点掌握前 7 个核心字段，就能满足日常使用需求。
01 meta - 版本信息（自动生成，无需修改）
由系统自动维护，记录配置文件最后修改的版本和时间，用于识别配置兼容性，手动修改易导致服务异常，直接忽略即可。
{"meta": {"lastTouchedVersion": "2026.3.13", // 最后修改的OpenClaw版本"lastTouchedAt": "2026-03-18T14:11:59.484Z" // 最后修改时间（UTC格式，自动生成）}}
02 auth - 认证配置（API Key 安全配置）
用于存储模型提供商、外部平台的认证信息，让 OpenClaw 能正常调用外部 API，敏感信息严禁明文填写，优先用环境变量引用。
{"auth": {"profiles": {"zai:default": { // 键名格式：提供商:别名"provider": "zai", // 模型提供商名称"mode": "api_key", // 认证方式，api_key为最常用"apiKey": "${ZAI_API_KEY}" // 环境变量引用，避免明文泄露},"openrouter:default": {"provider": "openrouter","mode": "api_key","apiKey": "${OPENROUTER_API_KEY}"}}}}
关键提示：provider名称必须与models字段中的提供商名称一致，否则会导致模型调用失败。
03 models - 模型配置（核心中的核心）
决定 Agent 运行时使用的模型、调用的 API 地址，是 OpenClaw 最核心的配置，新手必须重点掌握。
{"models": {"mode": "merge", // 模型加载模式，merge合并内置+自定义模型，推荐默认"providers": {"zai": { // 提供商名称，与auth中保持一致"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 // 是否启用推理能力，推荐开启}]}}}}
04 agents - Agent 配置（控制核心行为）
配置 Agent 的默认行为，包括默认模型、工作区路径、长对话优化等，新手只需修改默认主模型，其余保持默认即可。
{"agents": {"defaults": {"model": {"primary": "zai/glm-5", // 主模型，格式必须为「提供商/模型ID」"fallbacks": ["openrouter/xiaomi/mimo-v2-pro"] // 备用模型，主模型故障时自动切换},"workspace": "~/.openclaw/workspace", // 工作区路径，存储会话、日志等"compaction": { "mode": "safeguard" }, // 长对话优化模式，默认安全模式"heartbeat": 300 // 心跳检测时间（秒），5分钟检测一次Agent运行状态}}}
注意：修改工作区路径后，需手动创建对应文件夹，否则会导致文件存储失败。
05 tools - 工具配置（控制 Agent 工具权限）
灵活配置 Agent 可使用的工具，支持预设模板、黑白名单，新手推荐启用全部工具，后续按需禁止。
{"tools": {"profile": "full", // 预设模板，full启用全部工具，basic仅启用基础工具"deny": ["browser", "canvas"], // 禁止使用的工具名单，数组形式"allow": [], // 允许使用的工具，优先级高于deny，空数组表示允许未被禁止的工具"web": {"search": { "enabled": true }, // 启用网页搜索工具，推荐开启"timeout": 10 // 网页搜索超时时间（秒）}}}
06 channels - 渠道配置（对接飞书 / 企业微信）
配置 OpenClaw 与外部消息平台的对接，实现 Agent 接收、回复平台消息，以下为飞书完整配置示例，其他平台逻辑一致。
{"channels": {"feishu": {"enabled": true, // 启用飞书渠道，true=启用，false=禁用"appId": "cli_xxxxxxxxxx", // 飞书开发者平台获取的App ID"appSecret": "xxxxxxxxxxxxxxxxxxxxxx", // 飞书App Secret，注意保密"connectionMode": "websocket", // 连接方式，websocket长连接推荐，实时性强"streaming": true, // 消息流式输出，实时分段回复"timeout": 30 // 消息响应超时时间（秒）}}}
获取方式：App ID 和 App Secret 在「飞书开发者平台→应用管理→应用详情」中获取。
07 gateway - 网关配置（核心服务器设置）
控制 OpenClaw 网关的监听端口、运行模式、访问权限，修改后必须重启网关才能生效，新手保持默认即可避免端口冲突。
{"gateway": {"port": 18789, // 监听端口，默认18789，修改需避免端口占用"mode": "local", // 运行模式，local本地运行，public公网可访问"bind": "loopback", // 绑定地址，loopback仅本机可访问，更安全"auth": {"mode": "token", // 认证方式，token令牌认证，none无认证"token": "${GATEWAY_TOKEN}" // 认证令牌，环境变量引用},"timeout": 60 // 网关请求超时时间（秒）}}
重启命令：openclaw gateway restart
08 其他常用字段（简洁解析，按需修改）
以下字段日常使用频率较高，配置简单，新手无需深入研究，默认配置即可满足需求，按需调整即可：
- commands：控制/reset（重置会话）、/help（查看帮助）等斜杠命令的启用状态，默认全部启用；
- session：管理会话生命周期，可设置会话超时时间、定时重置，默认配置即可；
- plugins：配置扩展插件（自定义工具、模板等），新手后期进阶再配置；
- skills：配置可插拔技能（搜索、翻译、日历等），与 tools 配合使用，默认启用基础技能。
进阶配置：4 个高级字段（新手可跳过）
适合有一定基础、需要优化服务的用户，按使用频率排序，重点解决敏感信息安全、多 Agent 管理、故障排查等问题，按需学习即可。
01 env - 环境变量（安全存储敏感信息）
核心作用是安全存储 API Key、认证令牌等敏感信息，避免明文写在配置文件中，降低泄露风险，进阶用户必备。
{"env": {"ZAI_API_KEY": "xxxxx", // 单个环境变量，键名建议大写"vars": { // 批量定义环境变量，便于分类管理"GATEWAY_TOKEN": "xxxxxxxxxxxx","FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxxxx"}}}
引用方式：单个变量${ZAI_API_KEY}，批量变量${vars.GATEWAY_TOKEN}。
02 messages - 消息行为配置（优化交互体验）
控制 Agent 的消息回复样式、队列、已读回执等，可根据使用习惯自定义，提升交互体验。
{"messages": {"prefix": "[OpenClaw 回复] ", // 自定义回复前缀，方便区分Agent消息"queue": { "enabled": true, "maxSize": 10 }, // 消息队列，多用户使用建议启用"ack": { "enabled": true, "reaction": "✅" }, // 飞书已读回执，显示✅"format": "markdown" // 消息格式，markdown富文本，plain纯文本}}
03 bindings - 多 Agent 路由（团队协作必备）
实现一个网关管理多个 Agent，可按渠道、用户、关键词将消息路由到不同 Agent，适合团队使用，个人用户无需配置。
{"bindings": {"rules": [{"channel": "feishu", // 匹配飞书渠道"user": ["user1@feishu.com"], // 匹配指定用户"agent": "agent1" // 路由到指定Agent},{"keyword": ["技术", "开发"], // 匹配消息关键词"agent": "agent2"}]}}
04 logging - 日志配置（排查故障必备）
控制系统日志的级别、输出路径、保留时间，用于排查 Agent 运行失败、消息无法接收等问题，遇到故障时按需调整即可。
{"logging": {"level": "info", // 日志级别，debug详细日志（排查故障），info普通日志，error仅错误日志"path": "~/.openclaw/logs", // 日志输出路径，默认即可"maxSize": 100, // 单个日志文件最大大小（MB）"maxDays": 7 // 日志保留天数，自动清理过期日志}}
实用小贴士：配置必看注意事项
-
部分配置修改后需重启网关：修改 gateway、plugins、channels后，必须执行openclaw gateway restart，配置才能生效，其他字段无需重启； -
敏感信息安全第一：API Key、AppSecret、认证令牌等，优先用环境变量引用，严禁明文写入配置文件； -
新手配置原则：先修改 models、agents、channels核心字段，确保 Agent 能正常运行，进阶字段后期按需优化，不盲目修改不熟悉的字段； -
报错快速排查：服务无法运行大概率是JSON 语法错误（少逗号、单引号代替双引号），可检查语法格式，或恢复默认配置后重新修改。