跳转到主要内容
OpenClaw 会从 ~/.openclaw/openclaw.json 读取可选的 配置。如果文件缺失，OpenClaw 会使用安全默认值。 活动配置路径必须是常规文件。OpenClaw 所拥有的写入会以原子方式替换它（重命名到该路径），因此符号链接的 openclaw.json 会被替换其目标文件，而不是透过链接写入 - 请避免符号链接配置布局。如果你将配置保存在默认状态目录之外，请将 OPENCLAW_CONFIG_PATH 直接指向真实文件。 添加配置的常见原因：
  • 连接渠道并控制谁可以给机器人发消息
  • 设置模型、工具、沙箱隔离或自动化（cron、hooks）
  • 调整会话、媒体、网络或 UI
查看完整参考了解每个可用字段。 智能体和自动化在编辑配置前，应使用 config.schema.lookup 获取精确到字段级别的文档。使用本页获取面向任务的指导，并使用配置参考查看更完整的字段地图和默认值。
刚开始配置？ 使用 openclaw onboard 启动交互式设置，或查看配置示例指南获取可完整复制粘贴的配置。

​
最小配置

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

​
编辑配置

openclaw onboard       # full onboarding flow
openclaw configure     # config wizard

​
严格验证

OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关拒绝启动。唯一的根级例外是 $schema（字符串），这样编辑器可以附加 JSON Schema 元数据。
openclaw config schema 会打印 Control UI 和验证使用的规范 JSON Schema。config.schema.lookup 会获取单个路径范围内的节点，以及用于下钻工具的子项摘要。字段 title/description 文档元数据会贯穿嵌套对象、通配符（*）、数组项（[]）以及 anyOf/oneOf/allOf 分支。运行时插件和渠道 schema 会在清单注册表加载后合并进来。 验证失败时：
  • Gateway 网关不会启动
  • 只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
  • 运行 openclaw doctor 查看精确问题
  • 运行 openclaw doctor --fix（--repair 是同一个标志；--yes 会跳过提示）应用修复
Gateway 网关会在每次成功启动后保留一份受信任的最后已知良好副本，但启动和热重载不会自动恢复它 - 只有 openclaw doctor --fix 会这样做。如果 openclaw.json 验证失败（包括插件本地验证），Gateway 网关启动会失败，或重载会被跳过，并且当前运行时会保留最后接受的配置。被拒绝的写入也会保存为 <path>.rejected.<timestamp> 以供检查。Gateway 网关会阻止看起来像意外覆盖的写入 - 删除 gateway.mode、丢失 meta 块，或文件缩小超过一半 - 除非写入明确允许破坏性更改。当候选配置包含已遮盖的密钥占位符（例如 *** 或 [redacted]）时，会跳过提升为最后已知良好配置。

​
常见任务

每个渠道在 channels.<provider> 下都有自己的配置区段。请查看专用渠道页面了解设置步骤：所有渠道共享相同的私信策略模式：
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}
设置主模型和可选回退：
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}
  • agents.defaults.models 定义模型目录，并作为 /model 的允许列表；provider/* 条目会将 /model、/models 和模型选择器筛选到选定提供商，同时仍使用动态模型发现。
  • 使用 openclaw config set agents.defaults.models '<json>' --strict-json --merge 添加允许列表条目，而不会移除现有模型。若普通替换会移除条目，则会被拒绝，除非传入 --replace。
  • 模型引用使用 provider/model 格式（例如 anthropic/claude-opus-4-6）。
  • agents.defaults.imageMaxDimensionPx 控制转录/工具图像缩放（默认 1200）；较低的值通常会减少截图密集运行中的视觉 token 使用量。
  • 查看模型 CLI了解在聊天中切换模型，并查看模型故障转移了解凭证轮换和回退行为。
  • 对于自定义/自托管提供商，请参见参考中的自定义提供商。
私信访问通过每个渠道的 dmPolicy 控制（默认 "pairing"）：
  • "pairing"：未知发送者会收到一次性配对码以便批准
  • "allowlist"：只允许 allowFrom（或已配对允许存储）中的发送者
  • "open"：允许所有入站私信（需要 allowFrom: ["*"]）
  • "disabled"：忽略所有私信
对于群组，使用 groupPolicy（"allowlist" | "open" | "disabled"）以及 groupAllowFrom 或特定渠道的允许列表。查看完整参考了解每个渠道的详细信息。
群组消息默认需要提及。按智能体配置触发模式。普通群组/渠道回复会自动发布；对于智能体应自行决定何时发言的共享房间，可选择启用消息工具路径：
{
  messages: {
    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere
    groupChat: {
      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)
      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • 元数据提及：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
  • 文本模式：mentionPatterns 中的安全正则模式
  • 可见回复：messages.visibleReplies 可以要求全局使用消息工具发送；messages.groupChat.visibleReplies 会覆盖群组/渠道中的该设置。
  • 查看完整参考了解可见回复模式、按渠道覆盖以及自聊模式。
使用 agents.defaults.skills 设置共享基线，然后用 agents.list[].skills 覆盖特定智能体：
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}
  • 省略 agents.defaults.skills 时，默认不限制 Skills。
  • 省略 agents.list[].skills 时继承默认值。
  • 设置 agents.list[].skills: [] 表示没有 Skills。
  • 查看 Skills、Skills 配置 和配置参考。
控制 Gateway 网关重启看起来停滞的渠道的激进程度：
{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}
  • 显示的值是默认值。设置 gateway.channelHealthCheckMinutes: 0 可全局禁用健康监控重启。
  • channelStaleEventThresholdMinutes 应大于或等于检查间隔。
  • 使用 channels.<provider>.healthMonitor.enabled 或 channels.<provider>.accounts.<id>.healthMonitor.enabled，可在不禁用全局监控的情况下，为某个渠道或账号禁用自动重启。
  • 查看健康检查了解运维调试，并查看完整参考了解所有字段。
在负载较高或低功耗主机上，给本地客户端更多时间完成认证前 WebSocket 握手：
{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}
  • 默认值为 15000 毫秒。
  • OPENCLAW_HANDSHAKE_TIMEOUT_MS 对一次性服务或 shell 覆盖仍然具有优先级。
  • 请优先修复启动/事件循环停顿；这个旋钮适用于健康但预热期间较慢的主机。
在隔离的沙箱运行时中运行智能体会话：
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
先构建镜像 - 如果使用源码检出，请运行 scripts/sandbox-setup.sh；如果通过 npm 安装，请参阅沙箱隔离 § 镜像和设置中的内联 docker build 命令。请参阅沙箱隔离获取完整指南，并参阅完整参考了解所有选项。
面向公开 App Store 构建的基于中继的推送使用托管的 OpenClaw 中继：https://ios-push-relay.openclaw.ai。自定义中继部署需要有意独立的 iOS 构建/部署路径，其中继 URL 必须与 Gateway 网关中继 URL 匹配。如果你正在使用自定义中继构建，请在 Gateway 网关配置中设置：
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
等效 CLI：
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
此设置的作用：
  • 允许 Gateway 网关通过外部中继发送 push.test、唤醒提示和重连唤醒。
  • 使用由已配对 iOS 应用转发的注册作用域发送授权。Gateway 网关不需要部署范围的中继令牌。
  • 将每个基于中继的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关不能复用已存储的注册。
  • 让本地/手动 iOS 构建继续使用直接 APNs。基于中继的发送仅适用于通过中继注册的官方分发构建。
  • 必须与嵌入 iOS 构建的中继基准 URL 匹配，以便注册和发送流量到达同一个中继部署。
端到端流程：
  1. 安装官方 iOS 应用。
  2. 可选：仅在使用有意独立的自定义中继构建时，在 Gateway 网关上配置 gateway.push.apns.relay.baseUrl。
  3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都连接。
  4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用收据向中继注册，然后将基于中继的 push.apns.register 载荷发布到已配对的 Gateway 网关。
  5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 push.test、唤醒提示和重连唤醒。
运维说明：
  • 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接该应用，使其能够发布绑定到该 Gateway 网关的新中继注册。
  • 如果你发布指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。
兼容性说明：
  • OPENCLAW_APNS_RELAY_BASE_URL 和 OPENCLAW_APNS_RELAY_TIMEOUT_MS 仍可作为临时环境变量覆盖使用。
  • 自定义 Gateway 网关中继 URL 必须与嵌入 iOS 构建的中继基准 URL 匹配；公开 App Store 发布通道会拒绝自定义 iOS 中继 URL 覆盖。
  • OPENCLAW_APNS_RELAY_ALLOW_HTTP=true 仍然是仅限 loopback 的开发逃生口；不要在配置中持久保存 HTTP 中继 URL。
请参阅 iOS App 了解端到端流程，并参阅身份验证和信任流程了解中继安全模型。
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every：持续时间字符串（30m、2h）。设置为 0m 可禁用。默认值：30m。
  • target：last | none | <channel-id>（例如 discord、matrix、telegram 或 whatsapp）
  • directPolicy：面向私信风格 Heartbeat 目标的 allow（默认）或 block
  • 请参阅 Heartbeat 获取完整指南。
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention：从 sessions.json 中清理已完成的隔离运行会话（默认 24h；设置为 false 可禁用）。
  • runLog：按作业清理保留的 Cron 运行历史行。历史存储在 SQLite 中；maxBytes（默认 2_000_000）为兼容旧版文件后端运行日志而保留，keepLines 默认为 2000。
  • 请参阅 Cron 作业，了解功能概览和 CLI 示例。
在 Gateway 网关上启用 HTTP webhook 端点：
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}
安全说明：
  • 将所有 hook/webhook 载荷内容都视为不受信任的输入。
  • 使用专用的 hooks.token；不要复用有效的 Gateway 网关身份验证密钥（gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 或 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD）。
  • Hook 身份验证仅通过标头传递（Authorization: Bearer ... 或 x-openclaw-token）；查询字符串令牌会被拒绝。
  • hooks.path 不能是 /；请将 webhook 入口保留在专用子路径上，例如 /hooks。
  • 除非进行严格限定范围的调试，否则保持不安全内容绕过标志禁用（hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent）。
  • 如果启用 hooks.allowRequestSessionKey，也要设置 hooks.allowedSessionKeyPrefixes，以限定调用方选择的会话键。
  • 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格工具策略（例如仅消息传递，并尽可能启用沙箱隔离）。
请参阅完整参考，了解所有映射选项和 Gmail 集成。
使用独立工作区和会话运行多个隔离的智能体：
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}
请参阅 Multi-Agent 和完整参考，了解绑定规则和按智能体访问配置文件。
使用 $include 组织大型配置：
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • 单个文件：替换包含它的对象
  • 文件数组：按顺序深度合并（后者优先），最多支持 10 层嵌套
  • 同级键：在 include 之后合并（覆盖已包含的值）
  • 相对路径：相对于执行 include 的文件解析
  • 路径格式：include 路径不得包含空字节，并且在解析前后都必须严格短于 4096 个字符
  • OpenClaw 所有的写入：当一次写入只更改一个由单文件 include 支撑的顶级区段时，例如 plugins: { $include: "./plugins.json5" }，OpenClaw 会更新该被包含的文件，并保持 openclaw.json 不变
  • 不支持的直通写入：对于 OpenClaw 所有的写入，根 include、include 数组以及带有同级覆盖的 include 会失败关闭，而不是扁平化配置
  • 限制范围：$include 路径必须解析到保存 openclaw.json 的目录下。若要在多台机器或多个用户之间共享一棵目录树，请将 OPENCLAW_INCLUDE_ROOTS 设置为路径列表（POSIX 上为 :，Windows 上为 ;），列出 include 可以引用的其他目录。符号链接会被解析并重新检查，因此即使某个路径在词法上位于配置目录中，只要其真实目标逃逸出所有允许的根，仍会被拒绝。
  • 错误处理：针对缺失文件、解析错误、循环 include、无效路径格式和长度过长提供清晰错误

​
配置热重载

Gateway 网关会监视 ~/.openclaw/openclaw.json 并自动应用更改 - 大多数设置无需手动重启。 直接文件编辑在通过验证前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定，读取最终文件，并在不重写 openclaw.json 的情况下拒绝无效的外部编辑。OpenClaw 所有的配置写入在写入前使用相同的 schema 门禁（请参阅严格验证，了解适用于每次写入的覆盖/回滚规则）。 如果看到 config reload skipped (invalid config)，或启动时报出 Invalid config，请检查配置，运行 openclaw config validate，然后运行 openclaw doctor --fix 修复。请参阅 Gateway 网关故障排查获取检查清单。

​
重载模式

模式行为
hybrid（默认）立即热应用安全更改。对关键更改自动重启。
hot仅热应用安全更改。需要重启时记录警告 - 由你处理。
restart在任何配置更改时重启 Gateway 网关，无论是否安全。
off禁用文件监视。更改会在下次手动重启时生效。
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
哪些可以热应用，哪些需要重启

大多数字段都可以无停机热应用；某些热应用的部分只会重启对应的 子系统（渠道、cron、Heartbeat、健康监控），而不是整个 Gateway 网关。在 hybrid 模式下，需要重启 Gateway 网关的变更会自动处理。
类别字段是否需要重启 Gateway 网关？
渠道channels.*、web (WhatsApp) - 所有内置渠道和插件渠道否（重启该渠道）
智能体和模型agent、agents、models、routing否
自动化hooks、cron、agent.heartbeat否（重启该子系统）
会话和消息session、messages否
工具和媒体tools、skills、mcp、audio、talk否
插件配置plugins.entries.*、plugins.allow、plugins.deny、plugins.enabled否（重新加载插件运行时）
UI 和其他ui、logging、identity、bindings否
Gateway 网关服务器gateway.*（端口、绑定、认证、tailscale、TLS、HTTP、push）是
基础设施discovery、browser、plugins.load、plugins.installs是
gateway.reload 和 gateway.remote 是 gateway.* 下的例外 - 更改它们不会触发重启。各个插件也可以覆盖此表：已加载的插件可以声明自己的触发重启配置前缀（例如内置 Canvas 插件会针对 plugins.enabled、plugins.allow 和 plugins.deny 重启 Gateway 网关，而不仅仅是它自己的 plugins.entries.canvas），所以实际行为取决于哪些插件处于活动状态。

​
重新加载规划

当你编辑通过 $include 引用的源文件时，OpenClaw 会基于源文件编写时的布局来规划 重新加载，而不是基于扁平化后的内存视图。 这会让热重载决策（热应用还是重启）保持可预测，即使单个 顶级部分位于自己的包含文件中，例如 plugins: { $include: "./plugins.json5" }。如果源布局存在歧义，重新加载规划会失败并关闭。

​
配置 RPC（程序化更新）

对于通过 Gateway 网关 API 写入配置的工具，优先使用此流程：
  • config.schema.lookup 用于检查一个子树（浅层 schema 节点 + 子项 摘要）
  • config.get 用于获取当前快照和 hash
  • config.patch 用于局部更新（JSON 合并补丁：对象合并，null 删除；数组会在明确用 replacePaths 确认后替换，如果 条目会被移除）
  • config.apply 仅在你打算替换整个配置时使用
  • update.run 用于显式自更新并重启；如果重启后的会话应运行一个后续轮次，请包含 continuationMessage
  • update.status 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本
智能体应将 config.schema.lookup 作为精确 字段级文档和约束的第一入口。当它们需要更广泛的配置地图、默认值，或专用 子系统参考链接时，请使用 配置参考。
控制平面写入（config.apply、config.patch、update.run）会按 每个 deviceId+clientIp 每 60 秒 3 次请求进行速率限制。重启 请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。 update.status 是只读的，但属于管理员范围，因为重启哨兵可能 包含更新步骤摘要和命令输出尾部。
局部补丁示例： 
openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'
config.apply 和 config.patch 都接受 raw、baseHash、sessionKey、 note 和 restartDelayMs。一旦配置文件已经存在，这两个方法都需要 baseHash（没有现有配置的首次写入会跳过该检查）。 config.patch 还接受 replacePaths，这是一个配置路径数组，用来表明这些路径的数组 替换是有意的。如果补丁会用更少条目的数组替换或删除现有数组， Gateway 网关会拒绝该写入，除非该精确路径出现在 replacePaths 中；数组条目下的嵌套数组使用 []，例如 agents.list[].skills。这可以防止截断的 config.get 快照 静默覆盖路由或 allowlist 数组。当你打算替换完整配置时，请使用 config.apply。

​
环境变量

OpenClaw 会从父进程读取环境变量，另外还会读取：
  • 当前工作目录中的 .env（如果存在）
  • ~/.openclaw/.env（全局回退）
这两个文件都不会覆盖现有环境变量。你也可以在配置中设置内联环境变量： 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
如果启用且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键：
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
等效环境变量：OPENCLAW_LOAD_SHELL_ENV=1。默认 timeoutMs：15000。
在任何配置字符串值中使用 ${VAR_NAME} 引用环境变量：
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
规则：
  • 只匹配大写名称：[A-Z_][A-Z0-9_]*
  • 缺失或为空的变量会在加载时抛出错误
  • 使用 $${VAR} 转义以输出字面量
  • 可在 $include 文件内使用
  • 内联替换："${BASE}/v1" → "https://api.example.com/v1"
对于支持 SecretRef 对象的字段，你可以使用：
{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
SecretRef 详情（包括用于 env/file/exec 的 secrets.providers）见 Secrets Management。 支持的凭证路径列在 SecretRef Credential Surface 中。
有关完整优先级和来源，请参阅 Environment。

​
完整参考

完整的逐字段参考见 配置参考。
相关：配置示例 · 配置参考 · Doctor

​
相关