OpenClaw 完整配置指南：从入门到精通

什么是 OpenClaw 配置？

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 格式配置文件。如果文件不存在，OpenClaw 使用安全默认值。

为什么要自定义配置？

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

最简配置示例

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

配置编辑方式

方式一：交互式向导

openclaw onboard       # 完整引导流程
openclaw configure     # 配置向导

方式二：CLI 单行命令

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 的 Config Tab，表单由 config schema 渲染，带 Raw JSON 编辑器作为逃生口。

方式四：直接编辑 直接编辑 ~/.openclaw/openclaw.json，Gateway 会监控文件并自动应用变更（支持热重载）。

严格校验

⚠️ OpenClaw 仅接受完全匹配 schema 的配置。未知 key、类型错误或无效值会导致 Gateway 拒绝启动。

校验失败时：

• Gateway 不启动
• 仅诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
• 运行 openclaw doctor 查看具体问题
• 运行 openclaw doctor --fix（或 --yes）自动修复

常用配置任务

1. 连接频道（WhatsApp、Telegram、Discord 等）

每个频道都在 channels.<provider> 下有独立配置段：

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

支持的频道：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Google Chat、Mattermost、Microsoft Teams、IRC、Feishu、LINE、Matrix、Synology Chat、Nextcloud Talk、Nostr、Twitc 等 20+ 个平台。

2. 选择和配置模型

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models 定义模型目录并作为 /model 的允许列表
• 模型引用格式为 provider/model（如 anthropic/claude-opus-4-6）
• imageMaxDimensionPx 控制 transcript/tool 图片缩放（默认 1200px）

3. 控制谁能发消息给机器人

DM 访问通过 dmPolicy 控制：

4. 群组提及门控

群组消息默认需要 @提及。配置每个 agent 的模式：

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
}

5. 配置会话重置

{
  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）
• reset.mode：daily（每天）/ idle（空闲后）/ never（从不）

6. 启用沙箱隔离

在独立 Docker 容器中运行 agent 会话：

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

需先构建镜像：scripts/sandbox-setup.sh

完整配置参考

完整字段参考请查看：OpenClaw 配置完整参考

本指南基于 OpenClaw 官方文档