---
title: "理解配置结构"
description: "理解 OpenClaw 配置结构：openclaw.json、JSON5、strict schema、热加载、last-known-good、环境变量和密钥边界。"
verifiedAt: "2026-05-06"
---

OpenClaw 的主配置文件是 `~/.openclaw/openclaw.json`。它不是“所有字段都填满才专业”的大表，而是 Gateway、Agent、Channel、tools、models、sandbox、automation 的运行契约。

> [!NOTE]
> **这一章用 13 分钟换什么**：你会知道什么时候该用 onboarding、Control UI、`openclaw config set`、直接编辑文件；也会知道配置坏了为什么 Gateway 会拒绝启动，而不是“先凑合跑”。

## 1. 先把配置理解成运行契约

`openclaw.json` 管的不是一个功能，而是多组边界：


- Agent：workspace、skills、模型、bootstrap、sandbox。
- Channel：WhatsApp、Telegram、Discord、Slack 等入口。
- Session：不同人、不同群、不同账号的上下文隔离。
- Tools 和 plugins：Agent 能调用哪些能力。
- Gateway：端口、认证、Control UI、日志、热加载。
- Automation：heartbeat、cron、hooks。

如果文件不存在，OpenClaw 会使用 safe defaults（安全默认值）。真正需要配置，通常是因为你要接渠道、控访问、设模型、开 sandbox、调 session 或加自动化。

```mermaid
flowchart TD
    Config["openclaw.json"]
    Gateway["Gateway 基础设施"]
    Agent["Agent 工作单元"]
    Channel["Channel 消息入口"]
    Tools["Tools / Plugins"]
    Automation["Automation"]
    Security["访问与密钥边界"]

    Config --> Gateway
    Config --> Agent
    Config --> Channel
    Config --> Tools
    Config --> Automation
    Config --> Security

    style Config fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Security fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Agent fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

> [!IMPORTANT]
> **最小配置不是空配置的反面**：最小配置只表达当前需要的意图。每多一个字段，就多一个排障点和安全边界。

## 2. `openclaw.json` 必须是真实文件

官方最新配置文档特别强调：active config path 必须是 regular file（普通文件）。把 `~/.openclaw/openclaw.json` 做成 symlink（符号链接）不适合 OpenClaw 自己写配置，因为 atomic write（原子写入）可能替换路径，而不是保留 symlink。

如果你把配置放在默认状态目录之外，应该用：

```bash
OPENCLAW_CONFIG_PATH=/path/to/real/openclaw.json
```

| 做法 | 结果 |
|------|------|
| 默认 `~/.openclaw/openclaw.json` | 新手首选，最少出错 |
| `OPENCLAW_CONFIG_PATH` 指向真实文件 | 适合多实例或服务化部署 |
| symlink 到其他位置 | 不推荐，OpenClaw-owned writes 可能替换链接 |

> [!WARNING]
> **不要把同步系统放在配置写入路径中间**：如果你想跨机器同步配置，先搞清谁负责写文件、谁负责同步、谁负责回滚。入门阶段先用默认路径。

## 3. 新手怎么改配置

官方提供几种入口：`openclaw onboard`、`openclaw configure`、`openclaw config get/set/unset`、Control UI，以及直接编辑文件。

推荐顺序：

1. 第一次用 onboarding。
2. 小改动用 `openclaw config set`。
3. 想看结构用 Control UI。
4. 需要查字段约束时用 `openclaw config schema` 或 `config.schema.lookup`。
5. 已经理解 schema 时再直接编辑 JSON5。

```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 会从 live config schema 渲染表单，还能显示字段 `title` / `description` 等 docs metadata。对 Agent 或自动化工具来说，`config.schema.lookup` 是写配置前的第一站。

## 4. strict schema 不是限制，是保护

OpenClaw 只接受完全匹配 schema 的配置。未知字段、类型错误、非法值都会让 Gateway 拒绝启动；根级例外只有 `$schema` 字符串，方便编辑器挂 JSON Schema metadata。

这听起来严格，但对一个能调用工具、接消息、处理密钥的系统来说，这是保护。

| 配置错误 | OpenClaw 的处理 |
|------|------|
| 未知字段 | 拒绝启动或拒绝 reload |
| 类型不对 | 拒绝启动或拒绝 reload |
| plugin-local validation 失败 | reload 跳过，当前 runtime 保持最后一次接受的配置 |
| 明显 destructive clobber | 保存为 `.rejected.*` 供检查 |
| redacted secret 示例值参与候选 | 不提升为 last-known-good |

配置校验失败时，优先跑：

```bash
openclaw doctor
openclaw config validate
openclaw doctor --fix
```

> [!TIP]
> **last-known-good 不是自动魔法**：Gateway 会保留成功启动后的可信副本，但启动和热加载失败时不会无脑自动恢复。你仍然要看诊断，再决定是否用 `doctor --fix` 修复或恢复。

## 5. 最小配置只表达最小意图

官方最小例子通常表达两个核心意图：给 Agent 一个 workspace，给某个 channel 一个受控入口。

```json5
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
    },
  },
}
```

这不是“推荐照抄上线”的完整配置。真实使用时，你还要根据平台文档配置 token、allowlist、DM policy、群组策略、session、tools 和模型。

新手每次改配置前先问：

- 我接的是哪个渠道。
- 谁可以发消息给它。
- 群组是否必须 mention。
- Agent 在哪个 workspace 工作。
- 这个入口能用哪些 tools 和 skills。
- 这次改动能不能单独验证。

## 6. 热加载和重启怎么理解

Gateway 会监听 `openclaw.json`，很多配置可以自动应用。默认 reload mode 是 `hybrid`：安全改动热应用，关键基础设施改动自动重启。

| 类型 | 示例 | 是否通常需要重启 |
|------|------|------|
| 业务配置 | channels、agents、models、hooks、cron、heartbeat、session、tools、skills | 否 |
| Gateway 入口 | port、bind、auth、TLS、HTTP server | 是 |
| 基础设施 | discovery、canvasHost、plugins | 是 |
| reload / remote 自身 | `gateway.reload`、`gateway.remote` | 特殊例外 |

常见 reload mode：

| 模式 | 行为 |
|------|------|
| `hybrid` | 默认；安全改动热应用，关键改动自动重启 |
| `hot` | 只热应用安全改动；需要重启时只记录 warning |
| `restart` | 任意配置变化都重启 Gateway |
| `off` | 不监听文件变化，下次手动重启生效 |

新手只要记住：保存文件不等于已经生效。要看 logs、health、doctor 和 Gateway 状态。

## 7. 密钥不要写进公开配置

OpenClaw 会读取父进程环境变量，也会读取当前工作目录 `.env` 和 `~/.openclaw/.env`。这些文件不会覆盖已经存在的环境变量。

配置字符串里可以引用环境变量：

```json5
{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}
```

但环境变量引用不是加密。涉及 token、API key、Gateway auth、模型 key、OAuth 时，不要把明文写进教程仓、公开 workspace 或截图里。

| 内容 | 该放哪里 |
|------|------|
| 示例字段结构 | 公开文档可以写 |
| 假占位符 | 公开文档可以写 |
| 真 API key / token | 环境变量、私有凭据或 `~/.openclaw/` |
| OAuth / auth profiles / sessions | 不进 workspace git，不进公开仓 |

> [!CAUTION]
> **密钥缺失导致启动失败通常是好事**：不要为了“先跑起来”把空 key 或真 key 随便写进公开配置。失败比泄露更容易修。

## 8. 配置坏了先做什么

配置坏了不要先删文件重来。官方诊断入口包括 doctor、logs、health、status、config validate。

推荐排障顺序：

1. 看 Gateway 是否还能启动诊断命令。
2. 运行 `openclaw config validate`。
3. 运行 `openclaw doctor`。
4. 看日志里具体 schema path。
5. 需要自动修复时再跑 `openclaw doctor --fix`。
6. 回滚最近一次配置改动。
7. 只修一个字段，再验证。

如果你一次改了十个字段，就很难判断真正坏在哪里。

```mermaid
flowchart TD
    Broken["配置出错"]
    Validate["openclaw config validate"]
    Doctor["openclaw doctor"]
    Logs["openclaw logs"]
    Fix["openclaw doctor --fix"]
    Small["只修一个字段"]
    Status["openclaw gateway status"]

    Broken --> Validate
    Validate --> Doctor
    Doctor --> Logs
    Logs --> Fix
    Fix --> Small
    Small --> Status

    style Broken fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Small fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Status fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

## 9. 新手常见坑

- 直接复制完整配置，里面的字段自己并不理解。
- 把配置文件做成 symlink，又让 OpenClaw 自己写配置。
- 把明文密钥放进 `openclaw.json`。
- 以为 workspace 是安全沙箱。
- 配置 `open` 入口后没有 session 和 tools 限制。
- 保存文件后不看 reload 日志。
- 一次改十几个字段，导致诊断没有锚点。

## 10. 怎么判断配置健康

健康标准：

- `openclaw doctor` 没有关键配置错误。
- `openclaw health` 能反映 Gateway 当前状态。
- 每个 channel 都有明确访问控制。
- 每个 Agent 都有明确 workspace。
- 密钥来自环境变量或安全凭据，不在公开文件里。
- 改动范围小，能通过日志解释为什么生效。

配置的目标是让 OpenClaw 可运行、可审计、可恢复，而不是把所有字段填满。

> [!TIP]
> **稳定配置靠“一改一验”**：每次只改一个意图，立刻跑 validate、doctor 或 health；不要把 channel、Agent、模型和远程访问混在一次提交里。

## 11. 本章自检

1. 为什么不建议把 `openclaw.json` 做成 symlink？
2. strict schema 校验失败时，Gateway 会怎么处理？
3. 哪些配置通常热加载，哪些通常需要重启？

> [!IMPORTANT]
> **过关标准**：你能用一句话说清 —— “OpenClaw 配置不是越多越好，而是用 schema、热加载和诊断命令把运行边界变得可验证。”

## 12. 接下来去哪

<Cards>
  <Card href="/docs/openclaw/official/00-getting-started/workspace" title="配置 Agent Workspace" description="配置文件讲运行契约，workspace 讲 Agent 长期工作现场。" />
  <Card href="/docs/openclaw/official/01-gateway-runtime/gateway-configuration" title="Gateway 配置" description="继续深入 reload、health、doctor 和 Gateway 自身配置。" />
  <Card href="/docs/openclaw/official/01-gateway-runtime/agents" title="Agent 配置" description="继续看 workspace、repoRoot、skills allowlist、agentDir 和多 Agent 路由边界。" />
</Cards>

## 13. 官方资料

- [Configuration](https://docs.openclaw.ai/gateway/configuration)
- [Configuration reference](https://docs.openclaw.ai/gateway/configuration-reference)
- [Configuration examples](https://docs.openclaw.ai/gateway/configuration-examples)
- [Secrets management](https://docs.openclaw.ai/gateway/secrets)
- [Environment variables](https://docs.openclaw.ai/help/environment)
