详细配置指南
这篇文档聚焦 ~/.openclaw/openclaw.json 的字段说明与高频改动项。
如果你还没完成安装与基础跑通，建议先看：安装与配置。
一、openclaw.json 字段总表（完整顶层，可快速查）
下面这张表覆盖了核心配置文件的全部顶层字段（来自官方 schema）。
如果你只想先排查启动问题，可以先看 gateway、agents、models、channels、tools。
| 顶层字段 | 你可以把它理解为 | 常见场景 |
|---|---|---|
$schema | 配置 schema 标识 | 编辑器提示补全 |
meta | OpenClaw 自动写入的配置元信息 | 通常不手改 |
env | 环境变量导入与覆盖 | 统一管理密钥/变量 |
wizard | 向导运行记录 | 排查向导状态 |
diagnostics | 诊断与追踪 | 排查疑难问题 |
logging | 日志级别与日志文件 | 看报错、调试 |
update | 更新渠道与启动检查 | stable / beta / dev |
browser | 浏览器工具能力 | web 自动化相关 |
ui | 控制界面外观与助手展示 | UI 小调整 |
auth | 鉴权档案与失败退避 | 多模型提供商登录管理 |
models | 模型提供商与模型目录 | 选模型、配 API |
nodeHost | 节点代理能力 | 浏览器节点转发 |
agents | Agent 默认设置与多 Agent 列表 | 最常改 |
tools | 工具开关、白名单、黑名单 | 安全边界 |
bindings | 会话路由绑定规则 | 多 Agent 路由 |
broadcast | 广播路由策略 | 群发/分发策略 |
audio | 音频相关参数 | 语音能力 |
media | 媒体处理策略 | 上传文件名等 |
messages | 消息层行为 | 前缀、队列、TTS |
commands | 斜杠命令行为 | /config、/restart |
approvals | 审批策略 | 高风险操作审批 |
session | 会话范围与重置策略 | 对话隔离、生命周期 |
cron | 定时任务系统 | 自动任务 |
hooks | Webhook 入站 | 外部系统推送 |
web | Web 通道心跳与重连 | 控制端连接稳定性 |
channels | 各聊天渠道配置 | Telegram/Discord 等 |
discovery | 网关发现（mDNS/DNS-SD） | 局域网发现 |
canvasHost | Canvas 服务 | 可视化画布能力 |
talk | 语音合成相关 | Talk 模式 |
gateway | 网关端口、绑定、认证、远程 | 最关键 |
memory | 记忆后端与检索 | 长期记忆体验 |
skills | Skills 加载与安装 | 扩展能力 |
plugins | 插件系统开关与安装记录 | 插件化扩展 |
二、gateway 字段详解（完整，可当字典查）
这是最容易“配置错导致启动失败”的模块，建议优先读。
| 字段路径 | 说明（小白版） | 常见值 |
|---|---|---|
gateway.port | 网关端口 | 18789 |
gateway.mode | 运行本地网关还是远程模式 | local / remote |
gateway.bind | 绑定地址范围 | loopback / lan / tailnet / custom |
gateway.customBindHost | 自定义绑定地址 | 192.168.1.10 |
gateway.controlUi.enabled | 控制 UI 开关 | true |
gateway.controlUi.basePath | 控制 UI 路径前缀 | /openclaw |
gateway.controlUi.root | 控制 UI 静态资源目录 | dist/control-ui |
gateway.controlUi.allowedOrigins | 允许的前端来源 | ["https://xxx.com"] |
gateway.controlUi.allowInsecureAuth | 不安全认证提示开关 | false（建议） |
gateway.controlUi.dangerouslyDisableDeviceAuth | 关闭设备身份校验（危险） | false（强烈建议） |
gateway.auth.mode | 网关鉴权模式 | token / password / trusted-proxy / none |
gateway.auth.token | Token 鉴权密钥 | 自定义长字符串 |
gateway.auth.password | 密码鉴权密钥 | 自定义长字符串 |
gateway.auth.allowTailscale | 是否允许 Tailscale 相关鉴权路径 | true / false |
gateway.auth.rateLimit.maxAttempts | 最大失败次数 | 数字 |
gateway.auth.rateLimit.windowMs | 统计窗口（毫秒） | 数字 |
gateway.auth.rateLimit.lockoutMs | 锁定时长（毫秒） | 数字 |
gateway.auth.rateLimit.exemptLoopback | 是否豁免本机回环地址 | true / false |
gateway.auth.trustedProxy.userHeader | 反代用户头名称 | 例如 x-auth-user |
gateway.auth.trustedProxy.requiredHeaders | 反代必需头 | 字符串数组 |
gateway.auth.trustedProxy.allowUsers | 允许用户列表 | 字符串数组 |
gateway.trustedProxies | 可信反向代理 IP 列表 | ["127.0.0.1"] |
gateway.allowRealIpFallback | 缺少 X-Forwarded-For 时是否回退 X-Real-IP | false（默认更安全） |
gateway.tools.deny | HTTP 调用额外禁用工具 | 工具名数组 |
gateway.tools.allow | 从默认禁用中放行工具 | 工具名数组 |
gateway.channelHealthCheckMinutes | 渠道健康检查间隔 | 数字 |
gateway.tailscale.mode | Tailscale 模式 | off / serve / funnel |
gateway.tailscale.resetOnExit | 退出时是否重置 Tailscale 相关状态 | true / false |
gateway.remote.url | 远程网关地址 | ws:// 或 wss:// |
gateway.remote.transport | 远程传输方式 | ssh / direct |
gateway.remote.token | 远程模式 token | 字符串 |
gateway.remote.password | 远程模式 password | 字符串 |
gateway.remote.tlsFingerprint | TLS 指纹固定（防中间人） | sha256:... |
gateway.remote.sshTarget | SSH 目标 | user@host |
gateway.remote.sshIdentity | SSH 私钥路径 | 文件路径 |
gateway.reload.mode | 配置热重载策略 | off / restart / hot / hybrid |
gateway.reload.debounceMs | 重载防抖时间 | 数字 |
gateway.tls.enabled | 是否启用 TLS | true / false |
gateway.tls.autoGenerate | 是否自动生成证书 | true / false |
gateway.tls.certPath | 证书路径 | 文件路径 |
gateway.tls.keyPath | 私钥路径 | 文件路径 |
gateway.tls.caPath | CA 路径 | 文件路径 |
gateway.http.endpoints.chatCompletions.enabled | OpenAI 兼容 Chat Completions 接口开关 | true / false |
gateway.http.endpoints.responses.enabled | OpenAI 兼容 Responses 接口开关 | true / false |
gateway.http.endpoints.responses.maxBodyBytes | Responses 请求体大小上限 | 数字 |
gateway.http.endpoints.responses.maxUrlParts | URL 片段数量上限 | 数字 |
gateway.http.endpoints.responses.files.allowUrl | 是否允许文件 URL 输入 | true / false |
gateway.http.endpoints.responses.files.urlAllowlist | 文件 URL 白名单 | 字符串数组 |
gateway.http.endpoints.responses.files.allowedMimes | 文件 MIME 白名单 | 字符串数组 |
gateway.http.endpoints.responses.files.maxBytes | 单文件字节上限 | 数字 |
gateway.http.endpoints.responses.files.maxChars | 文件文本抽取上限 | 数字 |
gateway.http.endpoints.responses.files.maxRedirects | 文件 URL 最大重定向次数 | 数字 |
gateway.http.endpoints.responses.files.timeoutMs | 文件抓取超时 | 数字 |
gateway.http.endpoints.responses.files.pdf.maxPages | PDF 最大页数 | 数字 |
gateway.http.endpoints.responses.files.pdf.maxPixels | PDF 渲染像素上限 | 数字 |
gateway.http.endpoints.responses.files.pdf.minTextChars | PDF 最小文本阈值 | 数字 |
gateway.http.endpoints.responses.images.allowUrl | 是否允许图片 URL 输入 | true / false |
gateway.http.endpoints.responses.images.urlAllowlist | 图片 URL 白名单 | 字符串数组 |
gateway.http.endpoints.responses.images.allowedMimes | 图片 MIME 白名单 | 字符串数组 |
gateway.http.endpoints.responses.images.maxBytes | 单图大小上限 | 数字 |
gateway.http.endpoints.responses.images.maxRedirects | 图片 URL 最大重定向次数 | 数字 |
gateway.http.endpoints.responses.images.timeoutMs | 图片抓取超时 | 数字 |
gateway.nodes.browser.mode | Browser 节点路由策略 | auto / manual / off |
gateway.nodes.browser.node | 指定固定 Browser 节点 | 节点 ID |
gateway.nodes.allowCommands | 允许的 node 命令扩展 | 命令数组 |
gateway.nodes.denyCommands | 显式拒绝的 node 命令 | 命令数组 |
三、新手最常改的 6 组字段（建议优先掌握）
| 模块 | 常改字段 | 你会得到什么 |
|---|---|---|
agents.defaults | model.primary、workspace、heartbeat、sandbox | 决定默认模型、工作目录、心跳和隔离策略 |
channels | channels.<渠道名>.enabled、dmPolicy、allowFrom、groupPolicy | 控制谁能给你发消息、哪些群能触发 |
tools | tools.allow、tools.deny、tools.web.* | 控制工具可用范围与安全边界 |
session | scope、dmScope、reset.* | 控制会话隔离和自动重置 |
skills | skills.load.extraDirs、skills.entries.* | 追加技能目录、给技能单独配 key |
logging | level、file、consoleLevel | 排查问题时最常用 |
资料来源（官方一手）
核对时间：2026-02-23