openclaw/docs/gateway/configuration.zh-CN.md

summary	read_when
~/.clawdbot/moltbot.json 的所有配置选项及示例	添加或修改配置字段

配置 🔧

Moltbot 从 ~/.clawdbot/moltbot.json 读取可选的 JSON5 配置（支持注释和尾随逗号）。

如果文件不存在，Moltbot 使用安全的默认值（嵌入式 Pi 代理 + 每发送者会话 + 工作区 ~/clawd）。通常只需要配置以下内容：

• 限制谁可以触发机器人（channels.whatsapp.allowFrom、channels.telegram.allowFrom 等）
• 控制群组允许列表 + 提及行为
• 自定义消息前缀
• 设置代理的工作区
• 调整嵌入式代理默认值和会话行为

---

严格配置验证

Moltbot 只接受完全匹配架构的配置。 未知键、格式错误的类型或无效值会导致网关拒绝启动以确保安全。

验证失败时：

• 网关不会启动。
• 只允许诊断命令（例如：moltbot doctor、moltbot logs、moltbot health）。
• 运行 moltbot doctor 查看确切问题。
• 运行 moltbot doctor --fix 应用迁移/修复。

---

最小配置（推荐起点）

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

---

常用选项

环境变量

Moltbot 从父进程读取环境变量。另外加载：

• 当前工作目录的 .env（如果存在）
• ~/.clawdbot/.env 的全局回退

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

配置中的环境变量替换

可以使用 ${VAR_NAME} 语法在任何配置字符串值中引用环境变量：

{
  models: {
    providers: {
      "custom-provider": {
        apiKey: "${CUSTOM_API_KEY}"
      }
    }
  }
}

---

渠道配置

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,  // 可选出站块大小（字符）
      mediaMaxMb: 50  // 可选入站媒体上限（MB）
    }
  }
}

DM 策略说明：

值	说明
pairing	默认，未知发送者获得配对码；所有者必须批准
allowlist	只允许 allowFrom 中的发送者
open	允许所有入站 DM（需要 allowFrom 包含 "*"）
disabled	忽略所有入站 DM

Telegram

{
  channels: {
    telegram: {
      botToken: "123456:ABC...",
      allowFrom: ["5347394567"],  // 你的 Telegram 用户 ID
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

获取 Bot Token：

1. 在 Telegram 中找 @BotFather
2. 发送 /newbot 创建新机器人
3. 复制返回的 token

获取用户 ID： 给机器人发消息后，机器人会返回你的用户 ID。

Discord

{
  channels: {
    discord: {
      token: "YOUR_BOT_TOKEN",
      dm: {
        policy: "pairing",
        allowFrom: ["USER_ID"]
      },
      guilds: {
        "GUILD_ID": {
          channels: {
            "CHANNEL_NAME": { allow: true }
          }
        }
      }
    }
  }
}

Slack

{
  channels: {
    slack: {
      botToken: "xoxb-...",
      appToken: "xapp-...",
      channels: {
        "#general": { allow: true }
      }
    }
  }
}

---

代理配置

模型配置

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["openai/gpt-5"]
      },
      workspace: "~/clawd"
    }
  }
}

多代理配置

{
  agents: {
    defaults: {
      workspace: "~/clawd"
    },
    list: [
      {
        id: "main",
        default: true,
        identity: {
          name: "助手",
          emoji: "🦞"
        }
      },
      {
        id: "work",
        workspace: "~/clawd-work",
        model: "openai/gpt-5"
      }
    ]
  }
}

代理身份

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "小龙",
          theme: "友好的助手",
          emoji: "🦞",
          avatar: "avatars/lobster.png"
        }
      }
    ]
  }
}

---

群组聊天配置

提及门控

群组消息默认需要提及（元数据提及或正则模式）。

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@小龙", "小龙", "助手"]
        }
      }
    ]
  }
}

群组策略

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",  // open | disabled | allowlist
      groups: {
        "*": { requireMention: true }
      }
    },
    telegram: {
      groupPolicy: "allowlist",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

---

网关配置

{
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "your-secret-token"
    },
    tailscale: {
      mode: "off"  // off | serve | funnel
    }
  }
}

---

日志配置

{
  logging: {
    level: "info",
    file: "/tmp/moltbot/moltbot.log",
    consoleLevel: "info",
    consoleStyle: "pretty",  // pretty | compact | json
    redactSensitive: "tools"
  }
}

---

沙箱配置

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

---

完整示例

{
  // 代理设置
  agents: {
    defaults: {
      workspace: "~/clawd",
      model: {
        primary: "anthropic/claude-opus-4-5"
      }
    },
    list: [
      {
        id: "main",
        identity: {
          name: "小龙",
          emoji: "🦞"
        },
        groupChat: {
          mentionPatterns: ["@小龙", "小龙"]
        }
      }
    ]
  },

  // 网关设置
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "your-secret-token"
    }
  },

  // 渠道设置
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_BOT_TOKEN",
      allowFrom: ["YOUR_USER_ID"]
    },
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+8612345678901"]
    }
  },

  // 日志设置
  logging: {
    level: "info",
    consoleStyle: "pretty"
  }
}

---

更多信息

• 配置示例
• 安全指南
• 多代理配置