小ai：OpenClaw 配置手册 - openclaw.json 完全指南

小ai：OpenClaw 配置手册 openclaw.json 完全指南 🧩 小ai：OpenClaw 配置手册 openclaw.json 完全指南 Modified March 23 定义内联环境变量，供模型 API Key、插件凭据等引用。仅在进程环境缺少对应 key 时生效，不会覆盖已有环境变量。 代码示例： Code block JSON Copy { "env": { "OPENROUTER API KEY": "sk or xxxxx", "ZAI API KEY": "xxxxx", "vars": { "GROQ API KEY": "gsk xxxxx" }, "shellEnv": { "enabled": true, "timeoutMs": 15000 } } } 字段含义： 🎁 提示：环境变量还有两种来源：项目根目录的 .env 文件和 /.openclaw/.env。优先级：进程已有变量 openclaw.json 内联 .env 文件。 4.2 messages — 消息行为配置 控制回复前缀、ACK 反应、消息队列、入站防抖、TTS 等全局消息行为。 代码示例： Code block JSON Copy { "messages": { "responsePrefix": "auto", "ackReaction": "👀", "ackReactionScope": "group mentions", "removeAckAfterReply": false, "queue": { "mode": "collect", "debounceMs": 1000, "cap": 20 }, "inbound": { "debounceMs": 2000 } } } 字段含义： 字段 类型 说明 messages.responsePrefix string 回复前缀："auto"（自动用 Agent 名称/emoji）、固定字符串、或 ""（禁用） messages.ackReaction string 收到消息后的 ACK 表情反应，默认取 Agent 的 identity.emoji，否则 "👀" messages.ackReactionScope string ACK 范围：group mentions（仅群@，默认）、group all（所有群消息）、direct（私聊）、all（全部） messages.removeAckAfterReply boolean 回复完成后是否移除 ACK 反应 messages.queue.mode string 消息队列策略：collect（合并为一条）、steer（插队）、interrupt（中断当前回复） messages.queue.debounceMs number 队列防抖间隔（毫秒） messages.queue.cap number 队列最大容量 messages.inbound.debounceMs number 入站消息防抖（毫秒），将同一发送者的连续文本合并为一次 Agent 调用。0 禁用 4.3 bindings — 多 Agent 路由 将不同渠道、不同用户或群组的消息路由到不同的 Agent。适用于一个 Gateway 管理多个 Agent 的场景，即龙虾团队模式。 代码示例： Code block JSON Copy { "bindings": [ { "agentId": "home", "match": { "channel": "feishu", "peer": { "kind": "direct", "id": "ou xxx" } } }, { "agentId": "work", "match": { "channel": "feishu", "peer": { "kind": "group", "id": "oc yyy" } } } ] } 字段含义： 字段 类型 说明 bindings[].agentId string 目标 Agent ID（需在 agents.list 中定义） bindings[].match.channel string 渠道名：feishu、telegram、discord 等 bindings[].match.peer.kind string 对话类型：direct（私聊）或 group（群聊） bindings[].match.peer.id string 用户 open id（ou xxx）或群组 ID（oc xxx） bindings[].match.accountId string 多账号场景下的账号 ID（可选） 4.4 logging — 日志配置 控制系统日志的级别、输出位置和格式。 代码示例： Code block JSON Copy { "logging": { "level": "info", "file": "/tmp/openclaw/openclaw.log", "consoleLevel": "info", "consoleStyle": "pretty", "redactSensitive": "tools" } } 字段含义： 字段 类型 说明 logging.level string 日志级别：debug、info（默认）、warn、error logging.file string 日志文件路径。不设则默认 /tmp/openclaw/openclaw YYYY MM DD.log logging.consoleLevel string 控制台日志级别， verbose 时自动提升为 debug logging.consoleStyle string 控制台样式：pretty（美化）、compact（紧凑）、json logging.redactSensitive string 敏感信息脱敏：off（不脱敏）、tools（脱敏工具调用中的敏感内容） 4.5 browser — 浏览器配置 控制 OpenClaw 内置浏览器的行为，用于 Agent 的网页浏览和自动化操作。 代码示例： Code block JSON Copy { "browser": { "enabled": true, "evaluateEnabled": true, "defaultProfile": "openclaw", "profiles": { "openclaw": { "cdpPort": 18800 }, "user": { "cdpPort": 18801 } } } } 字段含义： 字段 类型 说明 browser.enabled boolean 是否启用浏览器工具 browser.evaluateEnabled boolean 是否允许 act:evaluate 和 wait fn 操作 browser.defaultProfile string 默认浏览器配置：openclaw（隔离浏览器）、user（用户浏览器） browser.profiles object 浏览器配置集合，key 为配置名 profiles. .cdpPort number CDP 调试端口 browser.color string 浏览器标识颜色（多配置区分用） 4.6 discovery — 网络发现配置 控制 mDNS（局域网设备发现）和 DNS SD（广域网服务发现）。 代码示例： Code block JSON Copy { "discovery": { "mdns": { "mode": "minimal" }, "wideArea": { "enabled": false } } } 字段含义： 字段 类型 说明 discovery.mdns.mode string mDNS 模式：minimal（默认，不暴露 CLI 路径和 SSH 端口）、full（完整信息）、off（关闭） discovery.wideArea.enabled boolean 是否启用 DNS SD 广域网发现 定义内联环境变量，供模型 API Key、插件凭据等引用。仅在进程环境缺少对应 key 时生效，不会覆盖已有环境变量。 代码示例： 字段含义： 🎁 提示：环境变量还有两种来源：项目根目录的 .env 文件和 /.openclaw/.env。优先级：进程已有变量 openclaw.json 内联 .env 文件。 提示：环境变量还有两种来源：项目根目录的 .env 文件和 /.openclaw/.env。优先级：进程已有变量 openclaw.json 内联 .env 文件。 4.2 messages — 消息行为配置 控制回复前缀、ACK 反应、消息队列、入站防抖、TTS 等全局消息行为。 代码示例： 字段含义： 字段 类型 说明 messages.responsePrefix string 回复前缀："auto"（自动用 Agent 名称/emoji）、固定字符串、或 ""（禁用） messages.ackReaction string 收到消息后的 ACK 表情反应，默认取 Agent 的 identity.emoji，否则 "👀" messages.ackReactionScope string ACK 范围：group mentions（仅群@，默认）、group all（所有群消息）、direct（私聊）、all（全部） messages.removeAckAfterReply boolean 回复完成后是否移除 ACK 反应 messages.queue.mode string 消息队列策略：collect（合并为一条）、steer（插队）、interrupt（中断当前回复） messages.queue.debounceMs number 队列防抖间隔（毫秒） messages.queue.cap number 队列最大容量 messages.inbound.debounceMs number 入站消息防抖（毫秒），将同一发送者的连续文本合并为一次 Agent 调用。0 禁用 字段 字段 类型 类型 说明 说明 messages.responsePrefix messages.responsePrefix string string 回复前缀："auto"（自动用 Agent 名称/emoji）、固定字符串、或 ""（禁用） 回复前缀："auto"（自动用 Agent 名称/emoji）、固定字符串、或 ""（禁用） messages.ackReaction messages.ackReaction string string 收到消息后的 ACK 表情反应，默认取 Agent 的 identity.emoji，否则 "👀" 收到消息后的 ACK 表情反应，默认取 Agent 的 identity.emoji，否则 "👀" messages.ackReactionScope messages.ackReactionScope string string ACK 范围：group mentions（仅群@，默认）、group all（所有群消息）、direct（私聊）、all（全部） ACK 范围：group mentions（仅群@，默认）、group all（所有群消息）、direct（私聊）、all（全部） messages.removeAckAfterReply messages.removeAckAfterReply boolean boolean 回复完成后是否移除 ACK 反应 回复完成后是否移除 ACK 反应 messages.queue.mode messages.queue.mode string string 消息队列策略：collect（合并为一条）、steer（插队）、interrupt（中断当前回复） 消息队列策略：collect（合并为一条）、steer（插队）、interrupt（中断当前回复） messages.queue.debounceMs messages.queue.debounceMs number number 队列防抖间隔（毫秒） 队列防抖间隔（毫秒） messages.queue.cap messages.queue.cap number number 队列最大容量 队列最大容量 messages.inbound.debounceMs messages.inbound.debounceMs number number 入站消息防抖（毫秒），将同一发送者的连续文本合并为一次 Agent 调用。0 禁用 入站消息防抖（毫秒），将同一发送者的连续文本合并为一次 Agent 调用。0 禁用 4.3 bindings — 多 Agent 路由 将不同渠道、不同用户或群组的消息路由到不同的 Agent。适用于一个 Gateway 管理多个 Agent 的场景，即龙虾团队模式。 代码示例： 字段含义： 字段 类型 说明 bindings[].agentId string 目标 Agent ID（需在 agents.list 中定义） bindings[].match.channel string 渠道名：feishu、telegram、discord 等 bindings[].match.peer.kind string 对话类型：direct（私聊）或 group（群聊） bindings[].match.peer.id string 用户 open id（ou xxx）或群组 ID（oc xxx） bindings[].match.accountId string 多账号场景下的账号 ID（可选） 字段 字段 类型 类型 说明 说明 bindings[].agentId bindings[].agentId string string 目标 Agent ID（需在 agents.list 中定义） 目标 Agent ID（需在 agents.list 中定义） bindings[].match.channel bindings[].match.channel string string 渠道名：feishu、telegram、discord 等 渠道名：feishu、telegram、discord 等 bindings[].match.peer.kind bindings[].match.peer.kind string string 对话类型：direct（私聊）或 group（群聊） 对话类型：direct（私聊）或 group（群聊） bindings[].match.peer.id bindings[].match.peer.id string string 用户 open id（ou xxx）或群组 ID（oc xxx） 用户 open id（ou xxx）或群组 ID（oc xxx） bindings[].match.accountId bindings[].match.accountId string string 多账号场景下的账号 ID（可选） 多账号场景下的账号 ID（可选） 4.4 logging — 日志配置 控制系统日志的级别、输出位置和格式。 代码示例： 字段含义： 字段 类型 说明 logging.level string 日志级别：debug、info（默认）、warn、error logging.file string 日志文件路径。不设则默认 /tmp/openclaw/openclaw YYYY MM DD.log logging.consoleLevel string 控制台日志级别， verbose 时自动提升为 debug logging.consoleStyle string 控制台样式：pretty（美化）、compact（紧凑）、json logging.redactSensitive string 敏感信息脱敏：off（不脱敏）、tools（脱敏工具调用中的敏感内容） 字段 字段 类型 类型 说明 说明 logging.level logging.level string string 日志级别：debug、info（默认）、warn、error 日志级别：debug、info（默认）、warn、error logging.file logging.file string string 日志文件路径。不设则默认 /tmp/openclaw/openclaw YYYY MM DD.log 日志文件路径。不设则默认 /tmp/openclaw/openclaw YYYY MM DD.log logging.consoleLevel logging.consoleLevel string string 控制台日志级别， verbose 时自动提升为 debug 控制台日志级别， verbose 时自动提升为 debug logging.consoleStyle logging.consoleStyle string string 控制台样式：pretty（美化）、compact（紧凑）、json 控制台样式：pretty（美化）、compact（紧凑）、json logging.redactSensitive logging.redactSensitive string string 敏感信息脱敏：off（不脱敏）、tools（脱敏工具调用中的敏感内容） 敏感信息脱敏：off（不脱敏）、tools（脱敏工具调用中的敏感内容） 4.5 browser — 浏览器配置 控制 OpenClaw 内置浏览器的行为，用于 Agent 的网页浏览和自动化操作。 代码示例： 字段含义： 字段 类型 说明 browser.enabled boolean 是否启用浏览器工具 browser.evaluateEnabled boolean 是否允许 act:evaluate 和 wait fn 操作 browser.defaultProfile string 默认浏览器配置：openclaw（隔离浏览器）、user（用户浏览器） browser.profiles object 浏览器配置集合，key 为配置名 profiles. .cdpPort number CDP 调试端口 browser.color string 浏览器标识颜色（多配置区分用） 字段 字段 类型 类型 说明 说明 browser.enabled browser.enabled boolean boolean 是否启用浏览器工具 是否启用浏览器工具 browser.evaluateEnabled browser.evaluateEnabled boolean boolean 是否允许 act:evaluate 和 wait fn 操作 是否允许 act:evaluate 和 wait fn 操作 browser.defaultProfile browser.defaultProfile string string 默认浏览器配置：openclaw（隔离浏览器）、user（用户浏览器） 默认浏览器配置：openclaw（隔离浏览器）、user（用户浏览器） browser.profiles browser.profiles object object 浏览器配置集合，key 为配置名 浏览器配置集合，key 为配置名 profiles. .cdpPort profiles. .cdpPort number number CDP 调试端口 CDP 调试端口 browser.color browser.color string string 浏览器标识颜色（多配置区分用） 浏览器标识颜色（多配置区分用） 4.6 discovery — 网络发现配置 控制 mDNS（局域网设备发现）和 DNS SD（广域网服务发现）。 代码示例： 字段含义： 字段 类型 说明 discovery.mdns.mode string mDNS 模式：minimal（默认，不暴露 CLI 路径和 SSH 端口）、full（完整信息）、off（关闭） discovery.wideArea.enabled boolean 是否启用 DNS SD 广域网发现 字段 字段 类型 类型 说明 说明 discovery.mdns.mode discovery.mdns.mode string string mDNS 模式：minimal（默认，不暴露 CLI 路径和 SSH 端口）、full（完整信息）、off（关闭） mDNS 模式：minimal（默认，不暴露 CLI 路径和 SSH 端口）、full（完整信息）、off（关闭） discovery.wideArea.enabled discovery.wideArea.enabled boolean boolean 是否启用 DNS SD 广域网发现 是否启用 DNS SD 广域网发现 4.7 cron — 定时任务配置 控制定时任务（Cron Jobs）的并发限制、会话保留和运行日志。 代码示例： 字段含义： 字段 类型 说明 cron.enabled boolean 是否启用定时任务系统 cron.maxConcurrentRuns number 最大并行定时任务数，默认 2 cron.sessionRetention string 完成的定时任务会话保留时长，如 "24h"。设 false 禁用清理 cron.runLog.maxBytes string 单个运行日志文件最大大小，默认 2mb cron.runLog.keepLines number 日志裁剪时保留的最新行数，默认 2000 字段 字段 类型 类型 说明 说明 cron.enabled cron.enabled boolean boolean 是否启用定时任务系统 是否启用定时任务系统 cron.maxConcurrentRuns cron.maxConcurrentRuns number number 最大并行定时任务数，默认 2 最大并行定时任务数，默认 2 cron.sessionRetention cron.sessionRetention string string 完成的定时任务会话保留时长，如 "24h"。设 false 禁用清理 完成的定时任务会话保留时长，如 "24h"。设 false 禁用清理 cron.runLog.maxBytes cron.runLog.maxBytes string string 单个运行日志文件最大大小，默认 2mb 单个运行日志文件最大大小，默认 2mb cron.runLog.keepLines cron.runLog.keepLines number number 日志裁剪时保留的最新行数，默认 2000 日志裁剪时保留的最新行数，默认 2000 4.8 secrets — 密钥管理配置 配置密钥提供程序，支持从环境变量、文件或外部命令获取敏感凭据。 代码示例： 字段含义： 字段 类型 说明 secrets.providers object 密钥提供程序集合 providers. .source string 来源类型：env（环境变量）、file（文件）、exec（外部命令） providers. .path string file 类型的文件路径 providers. .mode string file 的读取模式：json（JSON 解析）或 singleValue providers. .command string exec 类型的命令路径（必须为绝对路径） secrets.defaults object 各来源类型的默认提供程序 字段 字段 类型 类型 说明 说明 secrets.providers secrets.providers object object 密钥提供程序集合 密钥提供程序集合 providers. .source providers. .source string string 来源类型：env（环境变量）、file（文件）、exec（外部命令） 来源类型：env（环境变量）、file（文件）、exec（外部命令） providers. .path providers. .path string string file 类型的文件路径 file 类型的文件路径 providers. .mode providers. .mode string string file 的读取模式：json（JSON 解析）或 singleValue file 的读取模式：json（JSON 解析）或 singleValue providers. .command providers. .command string string exec 类型的命令路径（必须为绝对路径） exec 类型的命令路径（必须为绝对路径） secrets.defaults secrets.defaults object object 各来源类型的默认提供程序 各来源类型的默认提供程序 4.9 ui — 界面外观配置 控制原生应用界面的配色和 Agent 身份显示。 代码示例： 字段含义： 字段 类型 说明 ui.seamColor string 界面主题色（Talk Mode 气泡等） ui.assistant.name string 界面中显示的助手名称 ui.assistant.avatar string 助手头像：emoji、短文本、图片 URL 或 data URI 字段 字段 类型 类型 说明 说明 ui.seamColor ui.seamColor string string 界面主题色（Talk Mode 气泡等） 界面主题色（Talk Mode 气泡等） ui.assistant.name ui.assistant.name string string 界面中显示的助手名称 界面中显示的助手名称 ui.assistant.avatar ui.assistant.avatar string string 助手头像：emoji、短文本、图片 URL 或 data URI 助手头像：emoji、短文本、图片 URL 或 data URI 4.10 canvasHost — 画布服务配置 控制 Agent 可编辑的 HTML/JS 画布的 HTTP 服务。 代码示例： 字段含义： 字段 类型 说明 canvasHost.root string 画布文件根目录 canvasHost.liveReload boolean 是否启用实时重载 字段 字段 类型 类型 说明 说明 canvasHost.root canvasHost.root string string 画布文件根目录 画布文件根目录 canvasHost.liveReload canvasHost.liveReload boolean boolean 是否启用实时重载 是否启用实时重载 4.11 talk — 语音对话配置 macOS/iOS/Android 语音对话模式的默认设置，控制 TTS 语音、静默超时和打断行为。 代码示例： 字段含义： 字段 类型 说明 talk.voiceId string ElevenLabs 语音 ID talk.voiceAliases object 语音别名映射，如 {"Clawd": "EXAVITQu4vr..."} talk.modelId string TTS 模型 ID talk.outputFormat string 输出音频格式 talk.silenceTimeoutMs number 用户静默后发送转录的等待时间（毫秒） talk.interruptOnSpeech boolean 用户说话时是否打断当前播放 字段 字段 类型 类型 说明 说明 talk.voiceId talk.voiceId string string ElevenLabs 语音 ID ElevenLabs 语音 ID talk.voiceAliases talk.voiceAliases object object 语音别名映射，如 {"Clawd": "EXAVITQu4vr..."} 语音别名映射，如 {"Clawd": "EXAVITQu4vr..."} talk.modelId talk.modelId string string TTS 模型 ID TTS 模型 ID talk.outputFormat talk.outputFormat string string 输出音频格式 输出音频格式 talk.silenceTimeoutMs talk.silenceTimeoutMs number number 用户静默后发送转录的等待时间（毫秒） 用户静默后发送转录的等待时间（毫秒） talk.interruptOnSpeech talk.interruptOnSpeech boolean boolean 用户说话时是否打断当前播放 用户说话时是否打断当前播放 参考资料 1. OpenClaw 官方文档 https://docs.openclaw.ai 2. OpenClaw GitHub 仓库 https://github.com/openclaw/openclaw 📖 部署完小龙虾后，一旦出现故障或需要修改配置文件，OpenClaw的配置文件看起来是不是像天书？ 本文档完整梳理了 OpenClaw 配置文件 /.openclaw/openclaw.json 中所有24个顶层字段的含义与用法，基于 2026.3.13 版整理。 目标读者：OpenClaw 的进阶学习者，想了解 openclaw.json 配置文件的语法结构和用法。 前置条件：已完成 openclaw onboard 初始化 部署完小龙虾后，一旦出现故障或需要修改配置文件，OpenClaw的配置文件看起来是不是像天书？ 本文档完整梳理了 OpenClaw 配置文件 /.openclaw/openclaw.json 中所有24个顶层字段的含义与用法，基于 2026.3.13 版整理。 目标读者：OpenClaw 的进阶学习者，想了解 openclaw.json 配置文件的语法结构和用法。 前置条件：已完成 openclaw onboard 初始化 一、JSON 语法 OpenClaw 的所有配置都存储在 /.openclaw/openclaw.json 中。openclaw.json 就是一个 JSON 文件，掌握JSON的语法规则，能避免 90% 的配置错误。 1.1 什么是 JSON？ JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，说白了就是一种"用文字存储结构化数据"的方式。 1.2 JSON 的基本规则 1. 键值对结构 JSON 由一个个"键: 值"对组成，用冒号分隔： 左边的 "name" 是键，右边的 "OpenClaw" 是值。 2. 数据类型 类型 写法 示例 字符串 用双引号包裹 "hello" 数字 直接写，不加引号 123, 3.14 布尔值 只有两种 true, false 空值 表示"没有" null 数组 用方括号 ["a", "b", "c"] 对象 用花括号 {"key": "value"} 类型 类型 写法 写法 示例 示例 字符串 字符串 用双引号包裹 用双引号包裹 "hello" "hello" 数字 数字 直接写，不加引号 直接写，不加引号 123, 3.14 123, 3.14 布尔值 布尔值 只有两种 只有两种 true, false true, false 空值 空值 表示"没有" 表示"没有" null null 数组 数组 用方括号 用方括号 ["a", "b", "c"] ["a", "b", "c"] 对象 对象 用花括号 用花括号 {"key": "value"} {"key": "value"} ⚠️ 注意：OpenClaw配置文件会先用JSON Schema（一种检验JSON语法的语言）校验一遍，未知键、类型错误或无效值会导致 Gateway 拒绝启动。 注意：OpenClaw配置文件会先用JSON Schema（一种检验JSON语法的语言）校验一遍，未知键、类型错误或无效值会导致 Gateway 拒绝启动。 当校验失败时： • Gateway 网关不会启动，症状就是龙虾没反应 • 只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status） • 运行 openclaw doctor 以查看具体问题 • 运行 openclaw doctor fix进行修复 大部分gateway网关没有启动，都跟这个openclaw.json配置错误有关。 1.3 如何验证 JSON 是否正确 如果不确定 JSON 写得对不对，可以用这个在线工具 JSONLint 复制进去进行语法检查 JSONLint 二、典型openclaw.json配置文件 下面以我完成 openclaw onboard 初始化后，openclaw.json配置文件示例。 典型的 openclaw.json 包含以下顶层字段： 三、主要配置字段 3.1 meta — 版本信息 系统自动维护元数据，一般不需要手动修改。 代码示例： 字段含义： 字段 类型 说明 meta.lastTouchedVersion string OpenClaw 版本号 meta.lastTouchedAt string 校验时间 字段 字段 类型 类型 说明 说明 meta.lastTouchedVersion meta.lastTouchedVersion string string OpenClaw 版本号 OpenClaw 版本号 meta.lastTouchedAt meta.lastTouchedAt string string 校验时间 校验时间 3.2 wizard — 向导运行记录 由 CLI 向导（onboard、configure、doctor）写入的运行记录。 代码示例： 字段含义： 字段 类型 说明 wizard.lastRunAt string 最后运行向导的时间 wizard.lastRunVersion string 运行向导时的 OpenClaw 版本 wizard.lastRunCommit string Git commit hash wizard.lastRunCommand string 运行的命令：onboard / configure / doctor wizard.lastRunMode string 运行模式：local / remote 字段 字段 类型 类型 说明 说明 wizard.lastRunAt wizard.lastRunAt string string 最后运行向导的时间 最后运行向导的时间 wizard.lastRunVersion wizard.lastRunVersion string string 运行向导时的 OpenClaw 版本 运行向导时的 OpenClaw 版本 wizard.lastRunCommit wizard.lastRunCommit string string Git commit hash Git commit hash wizard.lastRunCommand wizard.lastRunCommand string string 运行的命令：onboard / configure / doctor 运行的