## 一、文档概览：这篇文档是干什么的？

**一句话理解：** 这篇文档是 OpenClaw 配置的“总览 + 快速入门”，解读配置文件放在哪、怎么改、有哪些常见任务可以做，以及出错了怎么办。

本文档由 AI 基于 OpenClaw 官方配置概览文档整理，仅供学习交流，不构成官方权威解释。实际配置请以 OpenClaw 官方文档为准。

 

## 二、配置文件基础

### 2.1 文件位置与格式

~/.openclaw/openclaw.json

 

- `~` 代表你的用户主目录

- 格式是 **JSON5**：比标准 JSON 更宽松——支持注释（`//`）和尾随逗号

**初学者提示：** 如果这个文件不存在，OpenClaw 会用安全的默认值运行。所以你不需要一开始就写完整配置，可以先用默认值跑起来，再根据需要逐步添加。

 

### 2.2 为什么要添加配置文件？

| 原因 | 说明 |

|------|------|

| 连接通道 | 接入 WhatsApp、Telegram 等平台，并控制谁能给机器人发消息 |

| 设置模型、工具、沙箱、自动化 | 选择用什么 AI 模型、开启哪些工具能力、是否隔离运行、设置定时任务 |

| 调整会话、媒体、网络、界面 | 控制对话记忆方式、图片处理、网络配置、控制台界面 |

 

### 2.3 最小配置示例

```json5

// ~/.openclaw/openclaw.json

{

  agents: { defaults: { workspace: "~/.openclaw/workspace" } },

  channels: { whatsapp: { allowFrom: ["+15555550123"] } },

}

```

这个示例展示了两件最基本的事：

1. **Agent 工作区**：机器人读写文件的位置

2. **Channel 访问控制**：只允许指定号码通过 WhatsApp 与机器人对话

 

## 三、四种编辑配置的方式

| 方式 | 命令/路径 | 适用场景 |

|------|-----------|----------|

| 交互式向导 | `openclaw onboard` / `openclaw configure` | 新手首次配置，跟着提示走 |

| CLI 单行命令 | `openclaw config get/set/unset` | 快速修改单个配置项 |

| 控制台 UI | http://127.0.0.1:18789 → Config 标签页 | 可视化编辑，最友好 |

| 直接编辑 | `~/.openclaw/openclaw.json` | 批量修改 |

 

**初学者推荐：** 控制台 UI 最友好，不用记字段名；交互式向导适合首次配置。

 

## 四、严格验证：最重要的规则

 

**核心规则：** OpenClaw 只接受完全符合规范的配置。

**什么情况会导致启动失败？**

- 写了规范里没有的 key（比如拼写错误）

- 类型不对（比如本该是字符串的地方写了数字）

- 值无效

 

**验证失败怎么办？**

网关不启动 → 运行 openclaw doctor 查看问题 → 运行 openclaw doctor --fix 修复

 

可用的诊断命令：

- `openclaw doctor`：查看具体问题

- `openclaw logs`：查看日志

- `openclaw health`：查看健康状态

- `openclaw status`：查看运行状态

 

**初学者提示：** 记住这条就够了——**配置写错了网关起不来，用 doctor 命令排查**。

 

## 五、常见配置任务（初学者必读）

 

### 5.1 设置 Channel（通道）

每个 channel 在 `channels.<provider>` 下有独立配置段。

**常用 channel：** WhatsApp、Telegram、Discord

**统一的私聊策略模式：**

```json5

{

  channels: {

    telegram: {

      enabled: true,

      botToken: "123:abc",

      dmPolicy: "pairing", // 关键：谁可以给机器人发私聊

      allowFrom: ["tg:123"],

    },

  },

}

```

**dmPolicy 的四种取值：**

| 值 | 含义 | 适用场景 |

|------|------|----------|

| `"pairing"`（默认） | 未知发送者收到配对码，需你批准 | **推荐**：私人使用 |

| `"allowlist"` | 只允许列表中的发送者 | 固定几个好友使用 |

| `"open"` | 允许所有人 | 公开机器人（需 `allowFrom: ["*"]`） |

| `"disabled"` | 忽略所有私聊 | 只用群聊功能 |

 

**⚠️ 重要安全提示：** 这是最重要的安全配置。如果不加限制，任何人知道你的机器人账号都能调用它，产生的 API 费用都算你的。

 

### 5.2 配置模型

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

      },

    },

  },

}

```

 

**关键点：**

- 模型引用格式：`provider/model`（如 `anthropic/claude-opus-4-6`）

- `imageMaxDimensionPx`：控制图片压缩尺寸（默认 1200），降低可减少图片识别费用

 

**初学者提示：** 模型 ID 必须一字不差。常用模型 ID 可以在各模型服务商的文档中查到。

 

### 5.3 控制谁能给机器人发消息

 

这部分在 5.1 已经涉及。群聊也有类似配置，使用 `groupPolicy` + `groupAllowFrom`。

 

### 5.4 群聊提及门控

 

**默认行为：** 群聊消息需要提及机器人才会响应。

```json5

{

  agents: {

    list: [

      {

        id: "main",

        groupChat: {

          mentionPatterns: ["@openclaw", "openclaw"], // 匹配这些文字就响应

        },

      },

    ],

  },

  channels: {

    whatsapp: {

      groups: { "*": { requireMention: true } }, // 必须 @ 才响应

    },

  },

}

```

 

**初学者提示：** 群聊建议开启 `requireMention: true`，否则群里有人 @ 所有人，机器人也会响应，可能造成困扰和费用浪费。

 

### 5.5 限制每个 Agent 的技能

 

**继承规则：**

| 配置情况 | 结果 |

|----------|------|

| 不写 `agents.defaults.skills` | 所有技能可用 |

| 不写 `agents.list[].skills` | 继承 defaults 中的技能 |

| 写 `agents.list[].skills: []` | 没有任何技能 |

 

```json5

{

  agents: {

    defaults: {

      skills: ["github", "weather"], // 默认都有这两个技能

    },

    list: [

      { id: "writer" }, // 继承：github, weather

      { id: "docs", skills: ["docs-search"] }, // 替换：只有 docs-search

      { id: "locked-down", skills: [] }, // 没有任何技能

    ],

  },

}

```

 

### 5.6 配置会话和重置

 

会话控制对话的记忆方式。

```json5

{

  session: {

    dmScope: "per-channel-peer", // 推荐用于多用户

    reset: {

      mode: "daily", // 每天重置

      atHour: 4, // 凌晨 4 点

      idleMinutes: 120, // 闲置 2 小时也重置

    },

  },

}

```

**dmScope 取值：**

- `main`：所有人共享一个会话（不推荐）

- `per-peer`：每人独立，但跨 channel 共享

- `per-channel-peer`：每人在每个 channel 独立（**多用户推荐**）

 

### 5.7 启用沙箱（安全功能）

 

在隔离的 Docker 容器中运行 agent，防止危险操作影响电脑。

 

```json5

{

  agents: {

    defaults: {

      sandbox: {

        mode: "non-main", // off | non-main | all

        scope: "agent",

      },

    },

  },

}

```

 

**前置要求：** 先运行 `scripts/sandbox-setup.sh` 构建镜像

 

**初学者提示：** 如果只是自己用、不执行危险命令，可以暂时不开沙箱。但公开机器人建议开启。

 

### 5.8 设置心跳（定期签到）

 

让机器人定期发消息确认在线状态。

```json5

{

  agents: {

    defaults: {

      heartbeat: {

        every: "30m", // 每 30 分钟一次，设 "0m" 禁用

        target: "last", // 发给最后活跃的 channel

      },

    },

  },

}

```

 

### 5.9 配置 Cron 定时任务

 

让机器人定时执行任务。

```json5

{

  cron: {

    enabled: true,

    maxConcurrentRuns: 2, // 同时最多跑 2 个任务

  },

}

```

 

### 5.10 配置多 Agent 路由

 

运行多个独立 agent，根据通道自动切换。

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

  ],

}

```

 

 

## 六、配置热重载（省时间技巧）

 

网关会自动监控配置文件，大多数设置改完**立即生效，无需重启**。

 

### 什么可以热应用，什么需要重启

| 类别 | 需要重启？ |

|------|-----------|

| Channels（WhatsApp、Telegram 等） | **否** |

| Agent 和模型 | **否** |

| 自动化（cron、heartbeat） | **否** |

| 会话和消息 | **否** |

| 工具和媒体 | **否** |

| 网关端口、认证、网络设置 | **是** |

 

**初学者提示：** 改配置前先看看——如果改的是“否”的部分，保存后立即生效；如果是“是”的部分，需要手动重启网关。

 

### 重载模式（可选配置）

```json5

{

  gateway: {

    reload: { mode: "hybrid", debounceMs: 300 }, // 默认就是 hybrid，不用改

  },

}

```

 

| 模式 | 行为 |

|------|------|

| `hybrid`（默认） | 安全更改即时生效，关键更改自动重启 |

| `hot` | 只即时生效安全更改，需要重启时只提醒你 |

| `restart` | 任何更改都重启 |

| `off` | 不监控文件，手动重启才生效 |

 

 

## 七、环境变量（安全存放敏感信息）

 

### 7.1 加载顺序

 

1. 系统已有的环境变量

2. 当前目录的 `.env` 文件

3. `~/.openclaw/.env` 文件

 

**注意：** 文件中的变量**不会覆盖**已存在的环境变量。

 

### 7.2 在配置中引用环境变量

```json5

{

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

}

```

 

**规则：**

- 用 `${VAR_NAME}` 格式

- 变量名只能用大写字母、下划线和数字

- 如果变量不存在，加载时会报错

- 想输出字面量 `${VAR}` 用 `$${VAR}`

 

### 7.3 内联环境变量（不推荐）

 

```json5

{

  env: {

    OPENROUTER_API_KEY: "sk-or-...", // 明文写在这里不安全

  },

}

```

 

**最佳实践：** 敏感信息（API Key、Token）用环境变量或 SecretRef，不要明文写在配置文件里。

 

 

## 八、初学者需要记住的 8 件事

 

1. **配置文件位置**：`~/.openclaw/openclaw.json`，JSON5 格式（支持注释）

2. **严格验证**：写错了网关起不来，用 `openclaw doctor` 排查

3. **安全第一**：`dmPolicy` 和 `allowFrom` 必须配置，否则任何人都能调用你的机器人

4. **四种编辑方式**：交互式向导、CLI 命令、控制台 UI、直接编辑，选自己顺手的

5. **热重载**：大多数配置改完立即生效，只有网关核心设置需要重启

6. **从最小配置开始**：先跑起来，再逐步添加配置项

7. **善用诊断命令**：`doctor`、`logs`、`health`、`status`

8. **敏感信息别明文写**：用环境变量 `${VAR}` 的方式引用