古法编程

Appearance

OpenClaw 网关从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置文件，支持注释和尾逗号。文件不存在时使用安全默认值。配置验证严格，未知键或格式错误会导致网关拒绝启动，此时只有 openclaw doctor 等诊断命令可用。使用 openclaw doctor --fix 修复配置问题，或恢复上次启动的好副本。大部分配置变更（渠道、模型、会话、工具、自动化）通过热重载自动生效，无需重启；网关服务器级别变更（端口、绑定、TLS、插件）需要重启，默认混合模式下自动处理。配置热重载支持四种模式：hybrid（默认，安全变更热应用，关键变更自动重启）、hot（仅热应用，手动处理重启）、restart（每次变更重启）、off（文件监视关闭）。

OpenClaw 配置文件怎么配：编辑、验证与热重载 ​

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 配置。openclaw.json 必须是常规文件；OpenClaw 自己的写入不支持符号链接布局，原子写入可能替换路径而非保留符号链接。如果配置放在默认状态目录之外，设置 OPENCLAW_CONFIG_PATH 指向实际文件路径。

如果文件缺失，OpenClaw 使用安全默认值。常见添加配置的原因：

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

所有可用字段的完整参考见配置参考。

提示：配置新手？ 从 openclaw onboard 开始交互式设置，或查看配置示例获取可直接复制的完整配置。

最简配置 ​

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

怎么编辑配置文件 ​

交互式向导

```bash
openclaw onboard       # 完整 onboarding 流程
openclaw configure     # 配置向导
```

CLI 单行命令

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

Control UI

打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **Config** 标签。Control UI 从配置 schema 渲染表单，包含字段 `title`/`description` 元数据以及插件和渠道 schema（如果可用），并提供一个 **Raw JSON** 编辑器作为备用。网关还提供 `config.schema.lookup` 用于工具获取单一路径作用域的 schema 节点及其下级摘要。

直接编辑

直接编辑 `~/.openclaw/openclaw.json`。网关会监视文件并自动应用变更（见[配置热重载](#config-hot-reload)）。

严格验证 ​

警告： OpenClaw 只接受完全匹配 schema 的配置。未知键、类型错误或无效值会导致网关拒绝启动。唯一的根级例外是 $schema（字符串），供编辑器附加 JSON Schema 元数据。

openclaw config schema 输出 Control UI 和验证使用的标准 JSON Schema。config.schema.lookup 获取单一路径作用域的节点及其下级摘要，用于 drill-down 工具。字段 title/description 元数据贯穿嵌套对象、通配符（*）、数组项（[]）以及 anyOf/oneOf/allOf 分支。运行时插件和渠道 schema 在清单注册表加载后合并。

验证失败时：

  • 网关不会启动
  • 只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
  • 运行 openclaw doctor 查看具体问题
  • 运行 openclaw doctor --fix（或 --yes）应用修复

网关在每次成功启动后会保留一份受信任的"上次好"副本。但启动和热重载不会自动恢复它。如果 openclaw.json 验证失败（包括插件本地验证），网关启动失败或跳过热重载，运行时保留上次接受的配置。运行 openclaw doctor --fix（或 --yes）修复前缀/错误覆盖的配置或恢复"上次好"副本。当候选配置包含编辑过的秘密占位符如 *** 时，不会提升为"上次好"。

常见配置任务 ​

渠道接入配置：WhatsApp、Telegram、Discord 等

每个渠道在 `channels.<provider>` 下有对应的配置段。查看专属渠道页面获取具体接入步骤：

- [WhatsApp](/ai/ai-tools/openclaw/channels/whatsapp) - `channels.whatsapp`
- [Telegram](/ai/ai-tools/openclaw/channels/telegram) - `channels.telegram`
- [Discord](/ai/ai-tools/openclaw/channels/discord) - `channels.discord`
- [Feishu](/ai/ai-tools/openclaw/channels/feishu) - `channels.feishu`
- [Google Chat](/ai/ai-tools/openclaw/channels/googlechat) - `channels.googlechat`
- [Microsoft Teams](/ai/ai-tools/openclaw/channels/msteams) - `channels.msteams`
- [Slack](/ai/ai-tools/openclaw/channels/slack) - `channels.slack`
- [Signal](/ai/ai-tools/openclaw/channels/signal) - `channels.signal`
- [iMessage](/ai/ai-tools/openclaw/channels/imessage) - `channels.imessage`
- [Mattermost](/ai/ai-tools/openclaw/channels/mattermost) - `channels.mattermost`

所有渠道共享相同的 DM 策略模式：

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 仅用于 allowlist/open
    },
  },
}
```

怎么选择和配置模型（主模型与降级模型）

设置主模型和可选降级模型：

```json5
{
  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` 和模型选择器到选定 provider，同时仍使用动态模型发现。
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目而不删除现有模型。直接替换会拒绝删除条目，除非传递 `--replace`。
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图片降噪缩放（默认 `1200`）；截图密集运行时适当降低通常能减少视觉 token 用量。
- 在聊天中切换模型见[模型 CLI](/ai/ai-tools/openclaw/concepts/models)，auth 轮换和降级行为见[模型降级](/ai/ai-tools/openclaw/concepts/model-failover)。
- 自定义/自托管 provider 见参考中的[自定义 provider](/ai/ai-tools/openclaw/gateway/config-tools#custom-providers-and-base-urls)。

控制谁可以给机器人发消息：dmPolicy 配置

每个渠道通过 `dmPolicy` 控制 DM 访问：

- `"pairing"`（默认）：未知发送者收到一次性配对码，需要审批
- `"allowlist"`：只允许 `allowFrom` 中的发送者（或已配对的允许存储）
- `"open"`：允许所有入站 DM（需要 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有 DM

群组消息使用 `groupPolicy` + `groupAllowFrom` 或渠道特定的允许列表。

每渠道详情见[完整参考](/ai/ai-tools/openclaw/gateway/config-channels#dm-and-group-access)。

群聊 @提及门控与消息可见回复配置

群组消息默认**需要提及**。按智能体配置触发模式。普通群组/频道回复自动发送；如果要在共享房间中让智能体自主决定何时说话，可选择消息工具路径：

```json5
{
  messages: {
    visibleReplies: "automatic", // 设为 "message_tool" 则所有可见输出都需要消息工具发送
    groupChat: {
      visibleReplies: "message_tool", // 可选项；可见输出需要 message(action=send)
      unmentionedInbound: "room_event", // 未提及的持续群组闲聊作为静默上下文
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
```

- **元数据提及**：原生 @-提及（WhatsApp 点击提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的安全正则模式
- **可见回复**：`messages.visibleReplies` 可以全局要求消息工具发送；`messages.groupChat.visibleReplies` 覆盖群组/频道的设置。
- 可见回复模式、每频道覆盖和自聊模式见[完整参考](/ai/ai-tools/openclaw/gateway/config-channels#group-chat-mention-gating)。

怎么限制每个智能体可用的技能

使用 `agents.defaults.skills` 设置共享基线，然后通过 `agents.list[].skills` 覆盖特定智能体：

```json5
{
  agents: {
    defaults: {
      skills: ["github", "weather"],
    },
    list: [
      { id: "writer" }, // 继承 github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换默认值
      { id: "locked-down", skills: [] }, // 无技能
    ],
  },
}
```

- 省略 `agents.defaults.skills` 则默认不限制任何技能。
- 省略 `agents.list[].skills` 则继承默认值。
- 设置 `agents.list[].skills: []` 则禁用所有技能。
- 见[技能](/ai/ai-tools/openclaw/tools/skills)、[技能配置](/ai/ai-tools/openclaw/tools/skills-config)和[配置参考](/ai/ai-tools/openclaw/gateway/config-agents#agents-defaults-skills)。

调整渠道健康监控参数

控制网关重启看起来停滞的渠道的激进程度：

```json5
{
  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` 为单个渠道或账户禁用自动重启，而不禁用全局监控。
- 运维调试见[健康检查](/ai/ai-tools/openclaw/gateway/health)，所有字段见[完整参考](/ai/ai-tools/openclaw/gateway/configuration-reference#gateway)。

怎么调整网关 WebSocket 握手超时时间

给本地客户端更多时间完成预认证 WebSocket 握手，适用于负载高或性能低的宿主机：

```json5
{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}
```

- 默认值为 `15000` 毫秒。
- `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 环境变量仍优先于配置。
- 建议先解决启动/事件循环延迟问题；此参数适用于正常但启动慢的宿主机。

怎么配置会话作用域和自动重置

会话控制对话连续性和隔离：

```json5
{
  session: {
    dmScope: "per-channel-peer",  // 多用户时推荐
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}
```

- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）。
- 会话作用域、身份链接和发送策略见[会话管理](/ai/ai-tools/openclaw/concepts/session)。
- 所有字段见[完整参考](/ai/ai-tools/openclaw/gateway/config-agents#session)。

怎么启用沙箱（Docker 容器隔离）

在隔离的沙箱运行时中运行智能体会话：

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
```

先构建镜像：从源码检出运行 `scripts/sandbox-setup.sh`，或从 npm 安装查看 `docker build` 命令，详情见[沙箱·镜像和设置](/ai/ai-tools/openclaw/gateway/sandboxing#images-and-setup)。

完整指南见[沙箱](/ai/ai-tools/openclaw/gateway/sandboxing)，所有选项见[完整参考](/ai/ai-tools/openclaw/gateway/config-agents#agentsdefaultssandbox)。

为官方 iOS 构建启用 Relay 推送

Relay 回退推送在 `openclaw.json` 中配置。

在网关配置中设置：

```json5
{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // 可选，默认：10000
          timeoutMs: 10000,
        },
      },
    },
  },
}
```

CLI 等效命令：

```bash
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
```

此功能的作用：

- 让网关通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
- 使用由已配对 iOS 应用转发的注册作用域发送授权。网关不需要部署范围的 relay token。
- 将每个 relay 支持的注册绑定到 iOS 应用配对的网关身份，防止其他网关复用存储的注册。
- 本地/手动 iOS 构建保持直接 APNs。Relay 支持的发送仅适用于通过 relay 注册的官方分发版本。
- 必须与官方/TestFlight iOS 构建中内置的 relay 基础 URL 匹配，确保注册和发送流量到达同一 relay 部署。

端到端流程：

1. 安装使用相同 relay URL 编译的官方/TestFlight iOS 构建。
2. 在网关配置中设置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与网关配对，让 node 和 operator 会话都连接。
4. iOS 应用获取网关身份，使用 App Attest 和应用收据向 relay 注册，然后将 relay 支持的 `push.apns.register` payload 发布到已配对的网关。
5. 网关存储 relay 句柄和发送授权，用于 `push.test`、唤醒提示和重连唤醒。

运维注意：

- 如果将 iOS 应用切换到不同网关，重新连接应用使其发布绑定到该网关的新 relay 注册。
- 如果发布指向不同 relay 部署的新 iOS 构建，应用会刷新缓存的 relay 注册而不是复用旧 relay 来源。

兼容性说明：

- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍作为临时环境变量覆盖有效。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限回环的开发逃生口；不要在配置中持久化 HTTP relay URL。

端到端流程见 [iOS App](/ai/ai-tools/openclaw/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型见[认证和信任流程](/ai/ai-tools/openclaw/platforms/ios#authentication-and-trust-flow)。

怎么配置心跳（周期性检入）

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
```

- `every`：持续时间字符串（`30m`、`2h`）。设置 `0m` 禁用。
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram`、或 `whatsapp`）
- `directPolicy`：`allow`（默认）或 `block`，用于 DM 风格的心跳目标
- 完整指南见[心跳](/ai/ai-tools/openclaw/gateway/heartbeat)。

怎么配置 cron 定时任务

```json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron 分派 + 隔离 cron 智能体轮次执行
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
```

- `sessionRetention`：从 `sessions.json` 清理已完成的隔离运行会话（默认 `24h`；设置 `false` 禁用）。
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
- 功能概览和 CLI 示例见 [Cron 定时任务](/ai/ai-tools/openclaw/automation/cron-jobs)。

怎么配置 webhook（hooks）

在网关启用 HTTP webhook 端点：

```json5
{
  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 payload 内容视为不可信输入。
- 使用专用 `hooks.token`；不要复用共享的网关 token。
- Hook 认证仅通过头部（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 被拒绝。
- `hooks.path` 不能是 `/`；将 webhook 入口放在专用子路径如 `/hooks`。
- 保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非在严格限定范围内调试。
- 如果启用 `hooks.allowRequestSessionKey`，同时设置 `hooks.allowedSessionKeyPrefixes` 限制调用者选择的会话键。
- 对于 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传输加适用时的沙箱）。

所有映射选项和 Gmail 集成见[完整参考](/ai/ai-tools/openclaw/gateway/configuration-reference#hooks)。

怎么配置多智能体路由

运行多个具有独立工作空间和会话的隔离智能体：

```json5
{
  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" } },
  ],
}
```

绑定规则和每智能体访问 profile 见[多智能体](/ai/ai-tools/openclaw/concepts/multi-agent)和[完整参考](/ai/ai-tools/openclaw/gateway/config-agents#multi-agent-routing)。

怎么使用 $include 拆分配置文件为多个文件

使用 `$include` 组织大型配置：

```json5
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
```

- **单个文件**：替换包含的对象
- **文件数组**：按顺序深度合并（后者优先）
- **同级键**：include 后合并（覆盖 include 的值）
- **嵌套 include**：支持最多 10 层
- **相对路径**：相对于包含文件解析
- **OpenClaw 自有写入**：当写入只改变一个由单个文件 include 支持的顶层段时（例如 `plugins: { $include: "./plugins.json5" }`），OpenClaw 更新那个文件而不改动 `openclaw.json`
- **不支持的写入穿透**：根级 include、include 数组以及带有同级覆盖的 include，对 OpenClaw 自有写入失败关闭，不会展平配置
- **路径限制**：`$include` 路径必须解析到 `openclaw.json` 所在目录之下。要在多台机器或用户间共享树，设置 `OPENCLAW_INCLUDE_ROOTS` 为额外目录的路径列表（POSIX 用 `:` 分隔，Windows 用 `;`）。符号链接会被解析并重新检查，因此语法上位于配置目录但实际目标逃逸所有允许根的路径仍被拒绝。
- **错误处理**：对缺失文件、解析错误和循环 include 给出清晰错误。

配置热重载 ​

网关监视 ~/.openclaw/openclaw.json 并自动应用变更——大多数设置无需手动重启。

直接文件编辑被视为不可信，直到它们通过验证。监视器等待编辑器临时写入/重命名操作稳定，然后读取最终文件，拒绝无效的外部编辑而不重写 openclaw.json。OpenClaw 自有的配置写入在写入前也使用相同 schema 门控；破坏性覆盖（如删除 gateway.mode 或文件缩小超过一半）会被拒绝并保存为 .rejected.* 文件供检查。

如果看到 config reload skipped (invalid config) 或启动报告 Invalid config，检查配置文件，运行 openclaw config validate，然后运行 openclaw doctor --fix 修复。见网关故障排除清单。

重载模式 ​

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

哪些字段热应用，哪些需要重启 ​

大多数字段无需停机即可热应用。在 hybrid 模式下，需要重启的变更会自动处理。

类别字段需要重启？
渠道channels.*、web（WhatsApp）——所有内置和插件渠道否
智能体与模型agent、agents、models、routing否
自动化hooks、cron、agent.heartbeat否
会话与消息session、messages否
工具与媒体tools、browser、skills、mcp、audio、talk否
UI 与其他ui、logging、identity、bindings否
网关服务器gateway.*（端口、绑定、认证、tailscale、TLS、HTTP）是
基础设施discovery、plugins是

注意： gateway.reload 和 gateway.remote 是例外——更改它们不会触发重启。

重载规划 ​

当编辑通过 $include 引用的源文件时，OpenClaw 从源文件布局规划重载，而非展平的内存视图。这使热重载决策（热应用 vs 重启）可预测，即使单个顶层段位于其自己的 include 文件中（例如 plugins: { $include: "./plugins.json5" }）。如果源布局不明确，重载规划失败关闭。

Config RPC（程序化更新） ​

对于通过网关 API 写入配置的工具，推荐流程：

  • config.schema.lookup 检查一个子树（浅 schema 节点 + 下级摘要）
  • config.get 获取当前快照加 hash
  • config.patch 进行部分更新（JSON merge patch：对象合并，null 删除，数组替换）
  • config.apply 仅当你打算替换整个配置时使用
  • update.run 进行明确的自我更新加重启；包含 continuationMessage 使重启后会话执行一个后续轮次
  • update.status 检查最新更新重启 sentinel 并验证重启后的运行版本

智能体应将 config.schema.lookup 作为获取准确字段级文档和约束的第一站。需要更广泛的配置映射、默认值或指向专用子系统参考的链接时使用配置参考。

注意： 控制平面写入（config.apply、config.patch、update.run）每 deviceId+clientIp 每 60 秒限制为 3 次请求。重启请求合并后强制执行重启周期间的 30 秒冷却。update.status 是只读的但受管理员作用域限制，因为重启 sentinel 可能包含更新步骤摘要和命令输出尾部。

部分补丁示例：

bash
openclaw gateway call config.get --params '{}'  # 获取 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 对两种方法都是必填的。

环境变量 ​

OpenClaw 从父进程读取环境变量，以及：

  • 当前工作目录的 .env（如果存在）
  • ~/.openclaw/.env（全局后备）

两个文件都不覆盖现有环境变量。你也可以在配置中设置内联环境变量：

json5
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Shell 环境导入（可选）

如果启用且预期的键未设置，OpenClaw 会运行你的登录 shell 并仅导入缺失的键：

json5
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

环境变量等效：OPENCLAW_LOAD_SHELL_ENV=1

配置值中的环境变量替换

在任何配置字符串值中用 ${VAR_NAME} 引用环境变量：

json5
{
  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"

Secret 引用（env、file、exec）

对于支持 SecretRef 对象的字段，可以使用：

json5
{
  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 详情（包括 secrets.providers 用于 env/file/exec）见秘密管理。 支持的凭证路径见 SecretRef 凭证面。

完整优先级和来源见环境。

完整参考 ​

字段级别的完整参考见 配置参考。

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

常见问题 ​

OpenClaw 配置文件在哪里？ ​

OpenClaw 从 ~/.openclaw/openclaw.json 读取 JSON5 格式的配置文件。如果文件不存在，使用安全默认值。可以使用 OPENCLAW_CONFIG_PATH 环境变量指定其他路径。

配置验证失败怎么办？ ​

OpenClaw 严格检查配置 schema，未知键或类型错误会导致网关拒绝启动。运行 openclaw doctor 查看具体错误，然后用 openclaw doctor --fix（或 --yes）自动修复。修复会替换为上次保存的好副本。

配置热重载没有生效怎么办？ ​

检查重载模式设置：gateway.reload.mode 默认是 hybrid，安全变更自动热应用，关键变更自动重启。如果设为 hot 或 off，需要手动处理重启。确认 openclaw.json 验证通过，运行 openclaw config validate。如果看到日志 config reload skipped (invalid config)，检查文件语法。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策