本页内容

本页内容

网关

配置

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置。如果文件不存在,则使用安全的默认值。

当前配置路径必须指向常规文件。OpenClaw 会通过重命名原子替换该路径,因此如果 openclaw.json 是符号链接,写入会替换这个链接,而不会沿链接写入目标文件。请避免使用符号链接配置。如果配置保存在默认状态目录之外,请将 OPENCLAW_CONFIG_PATH 直接指向实际文件。

添加配置的常见原因:

  • 连接通道并控制谁可以给机器人发消息
  • 设置模型、工具、沙箱或自动化(cron、hooks)
  • 调整会话、媒体、网络或 UI

有关全部可用字段,请参阅配置参考。

配置分为两类:根级同级字段存放基础设施设置和跨智能体的默认值,agents.defaults 则存放智能体循环的行为设置。在架构支持按智能体覆盖的情况下,agents.entries 中的条目可以覆盖任一类别的设置。

智能体和自动化工具在修改配置前,应使用 config.schema.lookup 获取准确的字段级文档。本页提供面向任务的指导;完整的字段映射和默认值,请参阅配置参考。

最小配置

json5
// ~/.openclaw/openclaw.json{  agents: { defaults: { workspace: "~/.openclaw/workspace" } },  channels: { whatsapp: { allowFrom: ["+15555550123"] } },}

编辑配置

交互式向导

bash
openclaw onboard       # full onboarding flowopenclaw configure     # config wizard

CLI(单行)

bash
openclaw config get agents.defaults.workspaceopenclaw config set agents.defaults.heartbeat.every "2h"openclaw config unset plugins.entries.brave.config.webSearch.apiKey

Control UI

打开 http://127.0.0.1:18789,使用 Config 标签页。Control UI 根据实时配置架构生成表单,包括字段的 title / description 文档元数据,以及可用的插件和渠道架构;也提供 Raw JSON 编辑器供直接编辑。对于需要逐层查看配置的界面和其他工具,Gateway 还提供 config.schema.lookup,可获取指定路径的架构节点及其直接子节点摘要。设置界面优先显示常用字段,高级字段则折叠在各章节的 Advanced (N) 分组中。使用 Show advanced 可展开全部分组。搜索始终涵盖两个层级,并按需展开匹配的高级分组。Settings -> Channels 下的渠道设置也采用相同方式,并共享 Show advanced 偏好;点击分隔线上的 Hide advanced 可再次折叠。

直接编辑

直接编辑~/.openclaw/openclaw.json。网关监视文件并自动应用更改(请参阅 hot reload)。

严格校验

openclaw config schema 输出 Control UI 和配置校验使用的权威 JSON Schema。config.schema.lookup 获取指定路径的节点和子节点摘要,供工具逐层查看。字段的 title/description 文档元数据会保留在嵌套对象、通配符(*)、数组项([])以及 anyOf/oneOf/allOf 分支中。加载清单注册表时,还会合并运行时插件和渠道的架构。

每个配置叶节点都通过 uiHints 指定为常用或高级显示层级。advanced: false 表示常用设置,advanced: true 表示高级设置。没有直接提示的叶节点会继承最近祖先的层级;如果祖先都未声明,则默认为高级。这只影响显示方式,不影响校验、默认值、重载行为或该键能否设置。

启动迁移使用与 openclaw doctor --fix 相同的固定转换,无需交互确认;仅当迁移后的整个配置(包括插件)通过校验时才写入。原配置保留在 .bak 轮换备份中。使用 $include、由 Nix 管理或由更新版本 OpenClaw 写入的配置不会自动迁移。适用条件和回退行为,请参阅旧版配置键迁移。

当验证仍然失败时:

  • Gateway 不会启动
  • 只有诊断命令可用(openclaw doctor、openclaw logs、openclaw health、openclaw status)
  • 运行 openclaw doctor 查看具体问题
  • 运行openclaw doctor --fix(--repair是相同的标志,--yes跳过提示)以应用修复

每次成功启动后,Gateway 都会保留一份可信的最近有效配置,但启动和热重载不会自动恢复它,只有 openclaw doctor --fix 才会恢复。如果经过适用的启动迁移(包括插件本地校验)后 openclaw.json 仍无效,Gateway 会启动失败。无效的热重载会被跳过,当前运行时继续使用最近接受的配置。如果写入因疑似意外覆盖而被阻止,OpenClaw 会尝试将拒绝的内容保存为 <path>.rejected.<timestamp> 供检查,并通过警告说明保存是否成功。如果保存失败,当前配置仍保持不变。对于疑似意外覆盖的写入,例如删除有效的 gateway.mode 或将文件缩小一半以上,Gateway 会予以阻止,除非写入明确允许破坏性更改。模式检查会先解析 $include 和环境变量引用。缺少 meta 会被记录为写入异常。如果候选配置包含 *** 或 [redacted] 等脱敏密钥占位符,则不会将其提升为最近有效配置。

配置页面

本页提供索引,较长的参考内容已拆分为四页。请打开与你的需求对应的页面。

页面 适用情况
常见任务 您需要通道、模型、访问规则、会话或自动化的复制粘贴配方。
配置热重载 编辑未生效,或者您需要知道是什么强制网关重新启动。
配置 RPC 工具通过网关 API 写入配置,而不是编辑文件。
环境变量 您正在决定 API 密钥所在的位置,或使用 ${VAR} 替换或秘密引用。

各章节的新位置

本页保留了原有的全部锚点,因此 /gateway/configuration#config-hot-reload 等既有链接仍可访问。每个条目都指向该内容现在所在的页面。

完整参考

有关完整的逐字段参考,请参阅 配置参考。


相关:配置Examples·配置参考·Doctor

相关内容

本页有帮助吗?