Skip to main content

​
配置

OpenClaw 会从 ~/.openclaw/openclaw.json 读取一个可选的 配置文件。 如果文件不存在，OpenClaw 将使用安全默认值。添加配置的常见原因包括：
  • 连接渠道并控制谁可以给机器人发消息
  • 设置模型、工具、沙箱环境或自动化（定时任务、钩子）
  • 调整会话、媒体、网络或 UI
请参阅所有可用字段的完整参考。
配置新手？ 请先运行 openclaw onboard 进行交互式设置，或查看 配置示例 指南，获取完整的复制粘贴配置。

​
最小配置

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

​
编辑配置

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

​
严格校验

OpenClaw 仅接受完全符合 schema 的配置。未知键、类型错误或无效值都会导致 Gateway 拒绝启动。唯一的根级例外是 $schema（字符串），允许编辑器附加 JSON Schema 元数据。
校验失败时：
  • Gateway 不启动
  • 仅诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
  • 运行 openclaw doctor 查看具体问题
  • 运行 openclaw doctor --fix（或 --yes）自动修复

​
常见任务

每个渠道都有自己的配置节，位于 channels.<provider> 下。请参见对应渠道页面的设置步骤：所有渠道共享相同的私信（DM）策略模式：
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 仅适用于 allowlist/open
    },
  },
}
设置主模型及可选的备用模型：
{
  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 控制转录/工具图像的缩放（默认 1200）；较低的数值通常在截图密集的运行中减少视觉令牌使用量。
  • 参见 模型命令行 以在聊天中切换模型，以及 模型故障转移 了解身份验证轮换和备用行为。
  • 自定义/自托管提供者请参阅参考中的自定义提供者。
私信访问通过渠道的 dmPolicy 控制：
  • "pairing"（默认）：未知发送者获得一次性配对码用于批准
  • "allowlist"：仅允许 allowFrom 中的发送者（或配对的允许存储）
  • "open"：允许所有入站私信（需设为 allowFrom: ["*"]）
  • "disabled"：忽略所有私信
群组请使用 groupPolicy + groupAllowFrom 或渠道特定的允许列表。详情请参阅完整参考。
群消息默认 需要提及。可按代理配置匹配模式：
{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}
  • 元数据提及：原生的 @-提及（WhatsApp 点击@，Telegram @bot 等）
  • 文本模式：mentionPatterns 中的正则表达式
  • 详见完整参考了解渠道覆盖和自聊模式
会话控制对话连续性和隔离：
{
  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：线程绑定的全局默认，会话路由（Discord 支持 /focus、/unfocus、/agents、/session idle 和 /session max-age）。
  • 详见 会话管理 了解作用域、身份链接和发送策略。
  • 详见完整参考获取所有字段。
在隔离的 Docker 容器中运行代理会话：
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}
请先构建镜像：scripts/sandbox-setup.sh详见沙箱环境指南及完整参考了解所有选项。
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every：时间间隔字符串（如 30m、2h），设置 0m 禁用。
  • target：last | whatsapp | telegram | discord | none
  • directPolicy：DM 风格心跳目标的策略，默认为 allow，可设为 block
  • 详见心跳指南
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}
  • sessionRetention：清理完成的隔离运行会话，默认 24 小时，设为 false 禁用。
  • runLog：限制 cron/runs/<jobId>.jsonl 文件大小及保留行数。
  • 详见定时任务获取功能概览和 CLI 示例。
在 Gateway 上启用 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 负载内容均视为不可信输入。
  • 除非进行严格范围的调试，否则保持不安全内容绕过标记（hooks.gmail.allowUnsafeExternalContent、hooks.mappings[].allowUnsafeExternalContent）关闭状态。
  • 钩子驱动的代理建议优先使用现代高级模型和严格的工具策略（例如仅限消息传递且尽可能使用沙箱）。
详见完整参考获取所有映射选项及 Gmail 集成。
运行多个隔离代理，使用独立的工作区和会话：
{
  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" } },
  ],
}
详情参见多代理及完整参考的绑定规则和每代理访问配置。
使用 $include 组织大型配置：
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • 单文件：替换包含对象
  • 文件数组：顺序深度合并（后者覆盖前者）
  • 同级键：合并在包含后，覆盖包含值
  • 嵌套包含：支持最多 10 层深度
  • 相对路径：相对于包含文件解析
  • 错误处理：缺少文件、解析错误和循环包含均有清晰报错

​
配置热重载

Gateway 会监视 ~/.openclaw/openclaw.json 并自动应用更改 — 大多数设置无需手动重启。

​
重载模式

模式行为
hybrid（默认）安全更改即时热应用。关键信息变更自动重启。
hot仅热应用安全更改。需要重启时记录警告，由你负责重启。
restart任何配置变更（安全或非安全）均重启 Gateway。
off关闭文件监视。变更仅在下次手动重启时生效。
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

​
哪些更改热应用，哪些需要重启

大部分字段可热应用且无停机。hybrid 模式会自动处理需要重启的更改。
分类字段需重启？
渠道channels.*、web（WhatsApp）— 所有内置及扩展渠道否
代理与模型agent, agents, models, routing否
自动化hooks, cron, agent.heartbeat否
会话与消息session, messages否
工具与媒体tools, browser, skills, audio, talk否
UI 与杂项ui, logging, identity, bindings否
Gateway 服务器gateway.*（端口、绑定、认证、tailscale、TLS、HTTP）是
基础架构discovery, canvasHost, plugins是
gateway.reload 和 gateway.remote 是例外——更改它们不会触发重启。

​
配置 RPC（编程式更新）

控制面写入 RPC（config.apply、config.patch、update.run）对每个 deviceId+clientIp 限制为每 60 秒最多 3 次请求。限制时，RPC 返回 UNAVAILABLE 并带 retryAfterMs。
验证并写入完整配置，同时重启 Gateway。
config.apply 会替换整个配置。部分更新请使用 config.patch，单键修改请用 openclaw config set。
参数：
  • raw（字符串）— 整个配置的 JSON5 内容
  • baseHash（可选）— 来自 config.get 的配置哈希（配置已存在时必须）
  • sessionKey（可选）— 重启后唤醒 ping 使用的会话密钥
  • note（可选）— 重启哨兵的注释
  • restartDelayMs（可选）— 重启前延迟，默认 2000 毫秒
重启请求在已有挂起/执行中的重启时会合并，且重启周期间隔为 30 秒冷却期。
openclaw gateway call config.get --params '{}'  # 获取 payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123"
}'
按 JSON 合并补丁语义，将部分更新合并到现有配置：
  • 对象递归合并
  • null 删除键
  • 数组替换
参数：
  • raw（字符串）— 仅包含要更改的键的 JSON5
  • baseHash（必填）— 来自 config.get 的配置哈希
  • sessionKey、note、restartDelayMs — 同 config.apply
重启行为与 config.apply 相同：合并挂起的重启请求并设 30 秒冷却。
openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

​
环境变量

OpenClaw 会读取父进程的环境变量，以及：
  • 当前工作目录下的 .env（如果存在）
  • ~/.openclaw/.env（全局备用）
两者都不会覆盖已有的环境变量。你还可以在配置中设置内联环境变量： 
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
如果启用且缺少预期的键，OpenClaw 会运行登录 shell，仅导入缺少的键：
{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}
等价环境变量：OPENCLAW_LOAD_SHELL_ENV=1
在任何配置字符串中，可以用 ${VAR_NAME} 引用环境变量：
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}
规则：
  • 仅匹配大写名称：[A-Z_][A-Z0-9_]*
  • 缺失或空值在加载时抛错
  • 用 $${VAR} 转义输出字面量
  • 可用于 $include 文件中
  • 内联替换例子："${BASE}/v1" → "https://api.example.com/v1"
对支持 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",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}
SecretRef 详情（包括 secrets.providers 的 env/file/exec）见秘密管理。支持的凭据路径列于SecretRef 凭据接口。
详见环境了解完整优先级和来源。

​
完整参考

字段逐项完整参考，请参阅 配置参考。
相关内容：配置示例 · 配置参考 · 诊断