网关配置

你的 gateway 配置块——各项放在哪里。绑定、认证与频道。快速链接：

配置 🔧

Moltbot 从 ~/.clawdbot/moltbot.json 读取可选 JSON5 配置（支持注释与尾逗号）。若文件不存在，Moltbot 使用较安全的默认值（嵌入式 Pi agent + 按发件人会话 + 工作区 ~/clawd）。通常只需在配置中：

限制谁可触发机器人（channels.whatsapp.allowFrom、channels.telegram.allowFrom 等）
控制群组白名单与 @ 提及行为（channels.whatsapp.groups、channels.telegram.groups、channels.discord.guilds、agents.list[].groupChat）
自定义消息前缀（messages）
设置 agent 工作区（agents.defaults.workspace 或 agents.list[].workspace）
调整嵌入式 agent 默认（agents.defaults）与会话行为（session）
设置每 agent 身份（agents.list[].identity）

初次配置？ 可参考配置示例获取完整示例与说明。

严格配置校验

Moltbot 仅接受完全符合 schema 的配置。未知键、类型错误或无效值会导致网关拒绝启动。校验失败时：

网关不会启动。
仅允许诊断命令（如 moltbot doctor、moltbot logs、moltbot health、moltbot status、moltbot service、moltbot help）。
运行 moltbot doctor 查看具体问题。
运行 moltbot doctor --fix（或 --yes）执行迁移/修复。

Doctor 除非显式使用 --fix/--yes，否则不会写入任何变更。

Schema 与 UI 提示

网关通过 config.schema 暴露配置的 JSON Schema 供 UI 编辑器使用。控制 UI 根据该 schema 渲染表单，并提供 Raw JSON 编辑器作为兜底。频道插件与扩展可为自身配置注册 schema 与 UI 提示，使频道设置在各应用中保持 schema 驱动。提示（标签、分组、敏感字段）随 schema 提供，便于客户端渲染表单而无需硬编码配置知识。

应用并重启（RPC）

使用 config.apply 可一步完成校验、写入完整配置并重启网关。会写入重启哨兵并在网关恢复后 ping 上次活跃会话。注意： config.apply 会整体替换配置。若只改少量键，请用 config.patch 或 moltbot config set。请备份 ~/.clawdbot/moltbot.json。参数：raw（字符串）— 完整配置的 JSON5；baseHash（可选）— 来自 config.get 的配置哈希（已有配置时必填）；sessionKey（可选）— 用于唤醒 ping 的上次活跃会话键；note（可选）— 写入重启哨兵的备注；restartDelayMs（可选）— 重启前延迟（默认 2000）。示例（经 gateway call）：先 moltbot gateway call config.get --params '{}' 获取 payload.hash，再 moltbot gateway call config.apply --params '{ "raw": "...", "baseHash": "<hash-from-config.get>", "sessionKey": "agent:main:whatsapp:dm:+15555550123", "restartDelayMs": 1000 }'。

部分更新（RPC）

使用 config.patch 将部分更新合并到现有配置，不覆盖无关键。采用 JSON 合并补丁语义：对象递归合并；null 表示删除键；数组整体替换。与 config.apply 一样会校验、写入配置、存储重启哨兵并安排网关重启（提供 sessionKey 时可选唤醒）。参数：raw（字符串）— 仅含要修改键的 JSON5；baseHash（必填）— 来自 config.get 的哈希；sessionKey、note、restartDelayMs 同上。示例：先 config.get 取哈希，再 config.patch 传入 raw 与 baseHash。

最小配置（推荐起点）


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

默认镜像一次性构建：scripts/sandbox-setup.sh。

自聊模式（推荐用于群控）

若希望机器人在群组中不响应 WhatsApp @ 提及（仅响应特定文本触发）：


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

配置包含（`$include`）

使用 $include 将配置拆成多个文件，便于：组织大配置（如按客户的 agent 定义）、跨环境共享通用设置、将敏感配置单独存放。基本用法：主配置中 "agents": { "$include": "./agents.json5" } 等；单文件会替换该键；多文件为数组时按顺序深度合并。合并规则：单文件替换含 $include 的对象；文件数组按顺序深度合并（后者覆盖前者）；可与兄弟键并存，兄弟键在 include 之后合并（覆盖被包含值）。路径：相对路径相对于包含文件；绝对路径原样使用；../ 可用。错误：缺失文件、解析错误、循环包含会报错并给出路径或包含链。示例：多客户法律场景下，主配置用 list: { "$include": ["./clients/mueller/agents.json5", "./clients/schmidt/agents.json5"] } 等合并各客户 agent 与 broadcast。

常用选项

环境变量与 `.env`

Moltbot 从父进程（shell、launchd/systemd、CI 等）读取环境变量，并加载：当前工作目录下的 .env（若存在）、全局回退 ~/.clawdbot/.env。两类 .env 都不会覆盖已有环境变量。也可在配置中内联提供环境变量（仅当进程环境中缺少该键时生效，同样不覆盖）：env: { OPENROUTER_API_KEY: "sk-or-...", vars: { GROQ_API_KEY: "gsk-..." } }。完整优先级与来源见环境。

`env.shellEnv`（可选）

可选便利：若启用且预期键都未设置，Moltbot 会执行登录 shell 并仅导入缺失的预期键（从不覆盖），相当于 source 你的 shell 配置。配置：env: { shellEnv: { enabled: true, timeoutMs: 15000 } }。等效环境变量：CLAWDBOT_LOAD_SHELL_ENV=1、CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000。

配置中的环境变量替换

可在任意配置字符串值中用 ${VAR_NAME} 引用环境变量，在配置加载时、校验前替换。规则：仅匹配大写环境变量名 [A-Z_][A-Z0-9_]*；缺失或空会报错；用 $${VAR} 输出字面 ${VAR}；可与 $include 一起用（被包含文件也会替换）。内联示例：baseUrl: "${CUSTOM_API_BASE}/v1" 等。

认证存储（OAuth + API 密钥）

Moltbot 将按 agent 的认证 profile（OAuth + API 密钥）存储在：<agentDir>/auth-profiles.json（默认 ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json）。详见 OAuth。旧版 OAuth 导入：~/.clawdbot/credentials/oauth.json。嵌入式 Pi agent 在 <agentDir>/auth.json 维护运行时缓存（自动管理，勿手动编辑）。旧版 agent 目录（多 agent 之前）：~/.clawdbot/agent/*（由 moltbot doctor 迁移到 ~/.clawdbot/agents/<defaultAgentId>/agent/*）。覆盖：OAuth 目录（仅旧版导入）CLAWDBOT_OAUTH_DIR；Agent 目录（默认 agent 根覆盖）CLAWDBOT_AGENT_DIR（推荐）、PI_CODING_AGENT_DIR（旧版）。首次使用时 Moltbot 会将 oauth.json 中的条目导入 auth-profiles.json。

`auth`

认证 profile 的可选元数据（不存储密钥）：将 profile ID 映射到 provider + mode（及可选 email），并定义用于故障转移的 provider 轮换顺序。示例：auth: { profiles: { "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" }, "anthropic:work": { provider: "anthropic", mode: "api_key" } }, order: { anthropic: ["anthropic:me@example.com", "anthropic:work"] } }。

更多配置项（各频道、models、session、gateway、discovery、cron 等）见上方快速链接；完整英文参考见英文网关配置。