OpenClaw 配置完全指南：从零开始掌握 AI 网关设置

OpenClaw 的配置系统是其强大功能的基石。无论你是第一次接触的新手，还是需要精细调优的资深用户，本文都将带你全面掌握从基础设置到高级功能的每一个细节。

配置文件位置

路径：~/.openclaw/openclaw.json

格式：JSON5 (支持注释 // 和尾随逗号 ,)

机制：可选配置。若文件不存在，系统将使用安全的默认值。

目录索引

快速开始与最小配置
四种配置编辑方式
严格验证与安全机制
常见核心配置任务
配置热重载机制
环境变量与密钥管理
总结与最佳实践

快速开始与最小配置

通常你需要添加配置的场景包括：连接消息频道、设置模型/工具/沙箱、或调整会话/网络/UI 设置。

新手入门提示

推荐运行 openclaw onboard 启动交互式向导。

或参考配置示例大全获取可直接复制的模板。

最小可行配置 (Hello World)

这是能运行 OpenClaw 的最简配置，仅指定工作区和允许的 WhatsApp 号码：

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

四种配置编辑方式

OpenClaw 提供灵活的编辑方式，请根据你的习惯选择：

1. 交互式向导 (推荐新手)

通过问答形式逐步生成配置，最不容易出错。

openclaw onboard       # 完整设置向导
openclaw configure     # 快速配置向导

2. CLI 命令行 (适合自动化/脚本)

直接读写配置项，适合集成到 DevOps 流程中。

# 获取配置值
openclaw config get agents.defaults.workspace

# 设置配置值
openclaw config set agents.defaults.heartbeat.every "2h"

# 删除配置项
openclaw config unset tools.web.search.apiKey

3. 控制 UI (可视化操作)

访问 http://127.0.0.1:18789，进入 Config 标签页。

表单模式：根据配置模式渲染友好表单。
Raw JSON：高级用户可直接编辑原始 JSON。

4. 直接编辑 (传统方式)

直接编辑 ~/.openclaw/openclaw.json 文件。

优势：配合编辑器插件（如 VS Code JSON5）效率极高。
特性：网关会自动监控文件变化并应用更改（参见热重载）。

严格验证与安全机制

重要警告
OpenClaw 实施严格模式验证。未知键、格式错误或无效值会导致网关拒绝启动。

唯一例外：根级的 $schema 字段（字符串），用于编辑器元数据。

验证失败时的行为

网关进程终止，无法启动。
仅诊断命令可用：openclaw doctor, openclaw logs, openclaw health, openclaw status。
修复步骤：
- 运行 openclaw doctor 查看具体错误详情。
- 运行 openclaw doctor --fix (或 --yes) 尝试自动修复常见错误。

常见核心配置任务

1. 设置消息频道

每个频道在 channels.<provider> 下独立配置。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 仅在 allowlist/open 模式下生效
    },
  },
}

支持的频道提供商：

WhatsApp (channels.whatsapp)
Telegram (channels.telegram)
Discord (channels.discord)
Slack (channels.slack)
Signal (channels.signal)
iMessage (channels.imessage)
Google Chat (channels.googlechat)
Mattermost (channels.mattermost)
MS Teams (channels.msteams)

2. 选择模型与备胎策略

设置主模型及故障转移（Fallback）模型。

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

模型目录：agents.defaults.models 定义了可用模型列表及 /model 命令的白名单。
引用格式：provider/model (如 anthropic/claude-opus-4-6)。
图像缩放：通过 agents.defaults.imageMaxDimensionPx 控制 (默认 1200px)。

3. 访问控制：谁可以发消息？

通过 dmPolicy 严格控制私信权限：

群组控制结合 groupPolicy + groupAllowFrom：

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

4. 群组提及门控 (Mention Gating)

默认情况下，Bot 在群组中仅响应提及。可按 Agent 自定义触发词：

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "小爪"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

元数据提及：平台原生的 @ 功能 (如 WhatsApp 点击提及)。
文本模式：匹配 mentionPatterns 中的正则表达式。

5. 会话管理 (Session Management)

控制对话的连续性、隔离性与重置策略。

{
  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：线程绑定会话的全局默认设置。
reset：定义每日重置或空闲超时重置策略。

6. 启用沙箱 (Sandbox)

在隔离的 Docker 容器中运行 Agent 会话，保障主机安全。

前置步骤：首先运行 scripts/sandbox-setup.sh 构建镜像。

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

7. 心跳检测 (Heartbeat)

防止会话因长时间空闲而断开或休眠。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",      // last | whatsapp | telegram | discord | none
        directPolicy: "allow", // allow | block
      },
    },
  },
}

every：间隔时间 (如 30m, 2h)。设为 0m 禁用。
target：心跳消息发送的目标频道。
directPolicy：DM 式心跳的发送策略。

8. 配置定时任务 (Cron)

启用自动化定时任务执行。

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

sessionRetention：从 sessions.json 清理已完成会话的时间窗口。
runLog：按大小和行数轮转运行日志。

9. 设置 Webhooks

启用 HTTP Webhook 端点以接收外部事件。

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

安全提示：将所有 Webhook 内容视为非信任输入。除非进行严格范围的调试，否则请保持不安全内容绕过标志禁用。

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

11. 拆分配置文件 (`$include`)

使用 $include 将大型配置模块化，便于维护。

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

包含规则：

单个文件：替换当前对象。
文件数组：按顺序深度合并（后者覆盖前者）。
同级键：在包含后合并（可覆盖包含的值）。
嵌套深度：支持最多 10 层嵌套包含。
路径解析：相对路径相对于包含文件本身解析。

配置热重载机制

网关默认监控配置文件变化，大多数设置修改后无需重启即可生效。

重载模式配置

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

热应用 vs 需重启对照表

注意：修改 gateway.reload 和 gateway.remote 本身不会触发重启，需手动重启以应用新的重载策略。

环境变量与密钥管理

OpenClaw 按以下优先级加载环境变量：

父进程环境变量
当前工作目录的 .env (若存在)
~/.openclaw/.env (全局备胎)
(注：文件中的变量不会覆盖已存在的环境变量)

1. 内联环境变量

直接在配置文件中定义：

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

2. Shell 环境导入

自动运行登录 Shell 导入缺失的变量：

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

(等效于设置 OPENCLAW_LOAD_SHELL_ENV=1)

3. 变量替换 (`${VAR}`)

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

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

替换规则：

仅匹配大写名称：[A-Z_][A-Z0-9_]*。
变量缺失或为空将在加载时报错。
使用 $${VAR} 转义以输出字面量 ${VAR}。
支持在 $include 文件中嵌套使用。
支持字符串拼接："${BASE}/v1" → "https://api.example.com/v1"。

4. SecretRef 对象

对于敏感字段，推荐使用结构化的 SecretRef 对象：

{
  models: {
    providers: {
      openai: { 
        apiKey: { 
          source: "env", 
          provider: "default", 
          id: "OPENAI_API_KEY" 
        } 
      },
    },
  },
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey",
        },
      },
    },
  },
}

支持的源类型：

env: 从环境变量读取。
file: 从文件读取。
exec: 从命令执行输出读取。

总结与最佳实践

OpenClaw 的配置设计遵循以下核心原则，助您构建稳健的 AI 网关：

核心哲学

配置是通往强大 AI 助手的大门。
从简单开始，逐步扩展，让你的 OpenClaw 既安全又高效地运行。

对于更详细的字段级参考，请查阅 完整配置参考手册。

posted @ 2026-03-12 18:38 JackYang 阅读(22) 评论(0) 收藏举报

刷新页面返回顶部