6.7 配置详解

本页介绍网关配置的关键机制：严格校验、配置拆分（$include）、运行时应用与环境变量加载等。

严格配置校验

OpenClaw 仅接受完全匹配 schema 的配置。未知键、类型错误或值非法会导致 Gateway 拒绝启动。

• 启动失败时，只允许诊断类命令（如 openclaw doctor、openclaw logs、openclaw health、openclaw status）。
• 使用 openclaw doctor 查看具体问题；需要时使用 openclaw doctor --fix（或 --yes）执行迁移/修复。
• 除非显式选择 --fix/--yes，Doctor 不会写入改动。

Schema + UI 提示

Gateway 通过 config.schema 暴露 JSON Schema，Control UI 会用它渲染表单，并提供 Raw JSON 编辑器兜底。插件可注册 schema 与 UI hints（字段标签、分组、敏感字段等），确保 UI 不需要硬编码配置知识。

配置应用与热更新（RPC）

整包应用：config.apply

config.apply 会验证 + 写入完整配置并重启 Gateway。它会写入重启哨兵，并在 Gateway 恢复后唤醒最近会话。注意：config.apply 会整体替换配置，请在执行前备份 ~/.openclaw/openclaw.json。

openclaw gateway call config.get --params '{}' # 先拿到 payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{
  agents: { defaults: { workspace: \"~/.openclaw/workspace\" } }
}
",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

局部更新：config.patch

config.patch 按 JSON merge patch 语义合并更新：

• 对象递归合并
• null 删除键
• 数组整体替换

openclaw gateway call config.get --params '{}' # 先拿到 payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{
  channels: { telegram: { groups: { \"*\": { requireMention: false } } } }
}
",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

最小配置（推荐起步）

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

首次运行建议先构建默认沙箱镜像：

scripts/sandbox-setup.sh

自聊模式（群组控制推荐）

以下配置会让 WhatsApp 群里只有特定触发词才响应；同时把自己手机号加入 allowlist 以启用“自聊模式”。

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

配置拆分（$include）

使用 $include 将配置拆成多个文件，适合大型配置、跨环境共享与敏感信息隔离。

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },

  // 单文件：替换该键对应对象
  agents: { $include: "./agents.json5" },

  // 多文件：按顺序深度合并（后者覆盖前者）
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [{ id: "main", workspace: "~/.openclaw/workspace" }],
}

合并规则

• 单文件：替换包含 $include 的对象
• 多文件：按顺序深度合并（后者覆盖前者）
• 与同级键并存时：同级键在 include 后合并，覆盖 include 值
• 同级键 + 数组/原始值：不支持（include 内容必须是对象）

// 同级键覆盖 include
{
  $include: "./base.json5", // { a: 1, b: 2 }
  b: 99,                     // 结果 { a: 1, b: 99 }
}

嵌套与路径解析

• 支持嵌套 include（最多 10 层）。
• 相对路径相对“被 include 的文件”解析；绝对路径原样使用。
• 支持 ../ 上级目录。

{ "$include": "./sub/config.json5" }
{ "$include": "/etc/openclaw/base.json5" }
{ "$include": "../shared/common.json5" }

错误处理

• 缺失文件：报出解析后的完整路径
• 解析错误：指出具体失败的 include 文件
• 循环引用：检测并报告 include 链

环境变量与 .env

OpenClaw 会读取父进程的环境变量，并额外加载：

• 当前工作目录的 .env
• 全局回退 ~/.openclaw/.env（$OPENCLAW_STATE_DIR/.env）

两者都不会覆盖已有环境变量。你也可以在配置中内联 env（仅在进程环境缺失时生效）：

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

env.shellEnv（可选）

启用后，如果关键变量尚未设置，OpenClaw 会运行登录 shell 并只导入缺失项（不覆盖已有值）。

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

等效环境变量：

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

配置内变量替换

任意字符串字段可用 ${VAR_NAME} 引用环境变量（加载时替换，校验前完成）：

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

• 仅匹配大写变量名：[A-Z_][A-Z0-9_]*
• 缺失或空值会在加载时抛错
• 用 $${VAR} 可输出字面量 ${VAR}
• 对 $include 也生效

认证存储位置

每个代理的 OAuth + API key 存在：

• <agentDir>/auth-profiles.json（默认：~/.openclaw/agents/<agentId>/agent/auth-profiles.json）
• 旧版 OAuth 导入：~/.openclaw/credentials/oauth.json
• 运行时缓存：<agentDir>/auth.json（自动管理，不要手改）