跳转至

配置

OpenClaw 会读取一个可选的 JSON5 配置文件 ~/.openclaw/openclaw.json。如果该文件不存在，OpenClaw 将使用安全默认值。

当前生效的配置路径必须是常规文件。OpenClaw 自身的写入会原子性地替换它（即重命名覆盖到该路径），因此符号链接的 openclaw.json 会使其目标被替换，而不是被直接写入——请避免符号链接的配置布局。如果你将配置放在默认状态目录之外，请将 OPENCLAW_CONFIG_PATH 直接指向真实文件。

添加配置的常见原因：

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

查看配置参考以了解所有可用字段。

配置遵循双桶规则：根级兄弟字段保存基础设施和跨代理默认值，而 agents.defaults 保存代理主循环行为。agents.entries 下的条目可以在 schema 支持按代理覆盖的地方覆盖任一桶。

代理和自动化在编辑配置之前，应使用 config.schema.lookup 获取精确的字段级文档。请使用本页面获取面向任务的指导，并通过配置参考获取更全面的字段映射和默认值。

Tip

刚接触配置？ 先从 openclaw onboard 开始进行交互式设置，或查看配置示例指南获取可直接复制粘贴的完整配置。

最小配置

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

编辑配置

openclaw onboard       # full onboarding flow
openclaw configure     # config wizard

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

打开 http://127.0.0.1:18789 并使用 Config 选项卡。 控制 UI 会根据实时配置 schema 渲染表单，包括字段的 title/description 文档元数据，以及可用的插件和渠道 schema，并将 Raw JSON 编辑器作为兜底编辑入口。对于下钻式 UI 和其他工具，网关还会暴露 config.schema.lookup，用于获取单个路径范围内的 schema 节点及其直接子节点的摘要。设置页面首先显示常用字段。每个部分将其高级字段放在折叠的 Advanced (N) 组中。使用 Show advanced 可展开所有组。设置搜索始终涵盖两个层级，并在需要时打开匹配的高级组。Settings -> Channels 下的按渠道设置使用相同的拆分方式，并共享 Show advanced 偏好，分隔条上的 Hide advanced 可再次折叠它们。

直接编辑 ~/.openclaw/openclaw.json。Gateway 会监视该文件并自动应用更改（参见热重载）。

严格校验

Warning

OpenClaw 只接受与 schema 完全匹配的配置。未知键、类型错误或无效值会导致 Gateway 拒绝启动。在启动 Gateway 之前，请运行 openclaw doctor --fix 修复旧版键。唯一根级例外是 $schema（字符串），这样编辑器就可以附加 JSON Schema 元数据。

openclaw config schema 会打印 Control UI 和校验所使用的规范 JSON Schema。config.schema.lookup 获取单个路径范围内的节点以及子节点摘要，供下钻式工具使用。字段的 title/description 文档元数据会贯穿嵌套对象、通配符（*）、数组项（[]）以及 anyOf/oneOf/allOf 分支。当 manifest 注册表加载后，运行时插件和渠道 schema 会合并进来。

每个配置叶子节点在 uiHints 中都有 common（常用）或 advanced（高级）展示层级。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 会阻止看起来像意外覆盖的写入——例如丢失有效的 gateway.mode 或将文件缩减超过一半——除非该写入明确允许破坏性更改。模式检查会先解析 $include 和环境变量引用。缺少 meta 会被记录为写入异常。当候选配置包含诸如 *** 或 [redacted] 之类的脱敏密钥占位符时，不会将其提升为最后已知良好副本。

配置页面

本页是一个索引。较长的参考章节位于四个页面中。打开 与你所需内容匹配的页面。

页面 何时阅读
常见任务 当你需要渠道、模型、访问规则、会话或自动化的复制粘贴配方时。
配置热重载 当编辑未生效，或你需要了解哪些更改会强制 Gateway 重启时。
配置 RPC 当工具通过 gateway API 写入配置，而不是编辑文件时。
环境变量 当你正在决定 API 密钥存放位置，或使用 ${VAR} 替换或 secret 引用时。

各章节迁移位置

本页过去发布的所有锚点都保留在这里，因此诸如 /gateway/configuration#config-hot-reload 的现有链接仍然可以解析。每个条目都指向 现在承载该内容的页面。

完整参考

如需完整的逐字段参考，请参阅 配置参考。

相关：配置示例 · 配置参考 · Doctor

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw