openclaw.json 配置文档入门学习笔记

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

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

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

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

二、配置文件基础

2.1 文件位置与格式

~/.openclaw/openclaw.json

- ~ 代表你的用户主目录 - 格式是 JSON5：比标准 JSON 更宽松——支持注释（//）和尾随逗号

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

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

| 原因 | 说明 | |------|------| | 连接通道 | 接入 WhatsApp、Telegram 等平台，并控制谁能给机器人发消息 | | 设置模型、工具、沙箱、自动化 | 选择用什么 AI 模型、开启哪些工具能力、是否隔离运行、设置定时任务 | | 调整会话、媒体、网络、界面 | 控制对话记忆方式、图片处理、网络配置、控制台界面 |

2.3 最小配置示例

// ~/.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. 下有独立配置段。

常用 channel： WhatsApp、Telegram、Discord

统一的私聊策略模式：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing", // 关键：谁可以给机器人发私聊
      allowFrom: ["tg:123"],
    },
  },
}

dmPolicy 的四种取值：

| 值 | 含义 | 适用场景 | |------|------|----------| | "pairing"（默认） | 未知发送者收到配对码，需你批准 | 推荐：私人使用 | | "allowlist" | 只允许列表中的发送者 | 固定几个好友使用 | | "open" | 允许所有人 | 公开机器人（需 allowFrom: ["*"]） | | "disabled" | 忽略所有私聊 | 只用群聊功能 |

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

5.2 配置模型

{
  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 群聊提及门控

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

{
  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: [] | 没有任何技能 |

{
  agents: {
    defaults: {
      skills: ["github", "weather"], // 默认都有这两个技能
    },
    list: [
      { id: "writer" }, // 继承：github, weather
      { id: "docs", skills: ["docs-search"] }, // 替换：只有 docs-search
      { id: "locked-down", skills: [] }, // 没有任何技能
    ],
  },
}

5.6 配置会话和重置

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

{
  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，防止危险操作影响电脑。

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

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

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

5.8 设置心跳（定期签到）

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

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 每 30 分钟一次，设 "0m" 禁用
        target: "last", // 发给最后活跃的 channel
      },
    },
  },
}

5.9 配置 Cron 定时任务

让机器人定时执行任务。

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // 同时最多跑 2 个任务
  },
}

5.10 配置多 Agent 路由

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

{
  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） | 否 | | 会话和消息 | 否 | | 工具和媒体 | 否 | | 网关端口、认证、网络设置 | 是 |

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

重载模式（可选配置）

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

| 模式 | 行为 | |------|------| | hybrid（默认） | 安全更改即时生效，关键更改自动重启 | | hot | 只即时生效安全更改，需要重启时只提醒你 | | restart | 任何更改都重启 | | off | 不监控文件，手动重启才生效 |

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

7.1 加载顺序

1. 系统已有的环境变量
2. 当前目录的 .env 文件
3. ~/.openclaw/.env 文件

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

7.2 在配置中引用环境变量

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

规则：

• 用 ${VAR_NAME} 格式
• 变量名只能用大写字母、下划线和数字
• 如果变量不存在，加载时会报错
• 想输出字面量 ${VAR} 用 $${VAR}

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

{
  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} 的方式引用