Skip to content

README _CN.md

Latest commit

 

History

History
478 lines (339 loc) · 26.6 KB

README _CN.md

File metadata and controls

478 lines (339 loc) · 26.6 KB
Raw

🦞 Moltbot — 个人 AI 助手

Clawdbot

蜕皮吧！蜕皮吧！

CI 状态 GitHub 发布 DeepWiki Discord MIT 许可证

Moltbot 是一个运行在你自己设备上的个人 AI 助手。 它在你已经使用的频道上回答你的问题（WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、Microsoft Teams、WebChat），以及扩展频道如 BlueBubbles、Matrix、Zalo 和 Zalo Personal。它可以在 macOS/iOS/Android 上说话和倾听，并可以渲染一个你控制的实时画布。网关只是控制平面——产品才是助手。

如果你想要一个个人的、单用户的助手，感觉本地、快速且始终在线，这就是它。

网站 · 文档 · 快速入门 · 更新 · 展示 · FAQ · 向导 · Nix · Docker · Discord

推荐设置：运行入门向导（moltbot onboard）。它会引导你完成网关、工作区、频道和技能的设置。CLI 向导是推荐的路径，适用于 macOS、Linux 和 Windows（通过 WSL2；强烈推荐）。 支持 npm、pnpm 或 bun。 新安装？从这里开始：快速入门

订阅（OAuth）：

模型说明：虽然支持任何模型，但我强烈推荐 Anthropic Pro/Max (100/200) + Opus 4.5 以获得长上下文强度和更好的提示注入抵抗能力。参见入门指南。

模型（选择 + 认证）

安装（推荐）

运行时要求：Node ≥22。

npm install -g moltbot@latest
# 或：pnpm add -g moltbot@latest

moltbot onboard --install-daemon

向导会安装网关守护进程（launchd/systemd 用户服务）使其保持运行。 遗留说明：clawdbot 作为兼容性垫片仍然可用。

快速入门（简述）

运行时要求：Node ≥22。

完整的新手指南（认证、配对、频道）：快速入门

moltbot onboard --install-daemon

moltbot gateway --port 18789 --verbose

# 发送消息
moltbot message send --to +1234567890 --message "来自 Moltbot 的问候"

# 与助手对话（可选择传回到任何已连接的频道：WhatsApp/Telegram/Slack/Discord/Google Chat/Signal/iMessage/BlueBubbles/Microsoft Teams/Matrix/Zalo/Zalo Personal/WebChat）
moltbot agent --message "发货清单" --thinking high

正在升级？更新指南（并运行 moltbot doctor）。

开发频道

  • stable：标记的发布版本（vYYYY.M.D 或 vYYYY.M.D-<patch>），npm dist-tag latest。
  • beta：预发布标签（vYYYY.M.D-beta.N），npm dist-tag beta（可能缺少 macOS 应用）。
  • dev：main 分支的最新状态，npm dist-tag dev（发布时）。

切换频道（git + npm）：moltbot update --channel stable|beta|dev。 详情：开发频道。

从源码构建（开发）

推荐使用 pnpm 进行源码构建。Bun 是可选的，用于直接运行 TypeScript。

git clone https://github.com/moltbot/moltbot.git
cd moltbot

pnpm install
pnpm ui:build # 首次运行时自动安装 UI 依赖
pnpm build

pnpm moltbot onboard --install-daemon

# 开发循环（TS 更改时自动重新加载）
pnpm gateway:watch

注意：pnpm moltbot ... 直接运行 TypeScript（通过 tsx）。pnpm build 生成 dist/ 用于通过 Node / 打包的 moltbot 二进制文件运行。

安全默认值（私信访问）

Moltbot 连接到真实的消息界面。将入站私信视为不受信任的输入。

完整安全指南：安全

Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Google Chat/Slack 上的默认行为：

  • 私信配对（dmPolicy="pairing" / channels.discord.dm.policy="pairing" / channels.slack.dm.policy="pairing"）：未知发送者会收到一个简短的配对代码，机器人不会处理他们的消息。
  • 使用以下命令批准：moltbot pairing approve <channel> <code>（然后将发送者添加到本地允许列表存储）。
  • 公开入站私信需要明确选择加入：设置 dmPolicy="open" 并在频道允许列表中包含 "*"（allowFrom / channels.discord.dm.allowFrom / channels.slack.dm.allowFrom）。

运行 moltbot doctor 来暴露有风险/配置错误的私信策略。

亮点

  • 本地优先网关 — 会话、频道、工具和事件的单一控制平面。
  • 多频道收件箱 — WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、BlueBubbles、Microsoft Teams、Matrix、Zalo、Zalo Personal、WebChat、macOS、iOS/Android。
  • 多代理路由 — 将入站频道/账户/对等点路由到隔离的代理（工作区 + 每代理会话）。
  • 语音唤醒 + 对话模式 — 适用于 macOS/iOS/Android 的始终在线语音，配合 ElevenLabs。
  • 实时画布 — 由代理驱动的视觉工作空间，具有 A2UI。
  • 一流工具 — 浏览器、画布、节点、cron、会话以及 Discord/Slack 操作。
  • 配套应用 — macOS 菜单栏应用 + iOS/Android 节点。
  • 入门 + 技能 — 向导驱动的设置，包含捆绑/管理/工作区技能。

Star 历史

Star 历史图表

我们到目前为止构建的所有内容

核心平台

频道

应用 + 节点

工具 + 自动化

运行时 + 安全

运维 + 打包

工作原理（简述）

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / BlueBubbles / Microsoft Teams / Matrix / Zalo / Zalo Personal / WebChat
               │
               ▼
┌───────────────────────────────┐
│            网关                │
│       （控制平面）             │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ Pi 代理（RPC）
               ├─ CLI（moltbot …）
               ├─ WebChat UI
               ├─ macOS 应用
               └─ iOS / Android 节点

关键子系统

Tailscale 访问（网关仪表板）

Moltbot 可以自动配置 Tailscale Serve（仅限 tailnet）或 Funnel（公开），同时网关保持绑定到回环地址。配置 gateway.tailscale.mode：

  • off：没有 Tailscale 自动化（默认）。
  • serve：通过 tailscale serve 进行仅限 tailnet 的 HTTPS（默认使用 Tailscale 身份标头）。
  • funnel：通过 tailscale funnel 进行公开 HTTPS（需要共享密码 auth）。

说明：

  • 启用 Serve/Funnel 时，gateway.bind 必须保持 loopback（Moltbot 强制执行此操作）。
  • 可以通过设置 gateway.auth.mode: "password" 或 gateway.auth.allowTailscale: false 来强制 Serve 需要密码。
  • 除非设置了 gateway.auth.mode: "password"，否则 Funnel 拒绝启动。
  • 可选：gateway.tailscale.resetOnExit 在关闭时撤消 Serve/Funnel。

详情：Tailscale 指南 · Web 表面

远程网关（Linux 很棒）

在小型 Linux 实例上运行网关是完全没问题的。客户端（macOS 应用、CLI、WebChat）可以通过 Tailscale Serve/Funnel 或 SSH 隧道连接，你仍然可以配对设备节点（macOS/iOS/Android）以在需要时执行设备本地操作。

  • 网关主机默认运行 exec 工具和频道连接。
  • 设备节点通过 node.invoke 运行设备本地操作（system.run、相机、屏幕录制、通知）。 简而言之：exec 在网关所在的地方运行；设备操作在设备所在的地方运行。

详情：远程访问 · 节点 · 安全

通过 Gateway 协议进行 macOS 权限管理

macOS 应用可以在节点模式下运行，并通过 Gateway WebSocket（node.list / node.describe）通告其功能 + 权限映射。然后客户端可以通过 node.invoke 执行本地操作：

  • system.run 运行本地命令并返回 stdout/stderr/退出代码；设置 needsScreenRecording: true 以需要屏幕录制权限（否则你会得到 PERMISSION_MISSING）。
  • system.notify 发布用户通知并在拒绝通知时失败。
  • canvas.*、camera.*、screen.record 和 location.get 也通过 node.invoke 路由，并遵循 TCC 权限状态。

提升的 bash（主机权限）与 macOS TCC 分开：

  • 使用 /elevated on|off 在启用 + 允许列表时切换每会话提升访问。
  • Gateway 通过 sessions.patch（WS 方法）持久化每会话切换，与 thinkingLevel、verboseLevel、model、sendPolicy 和 groupActivation 一起。

详情：节点 · macOS 应用 · Gateway 协议

Agent 到 Agent（sessions_* 工具）

  • 使用这些工具在没有跳过聊天界面的情况下协调跨会话的工作。
  • sessions_list — 发现活动会话（agents）及其元数据。
  • sessions_history — 获取会话的脚本日志。
  • sessions_send — 向另一个会话发送消息；可选的回复回乒乓 + 公告步骤（REPLY_SKIP、ANNOUNCE_SKIP）。

详情：会话工具

技能注册表（ClawdHub）

ClawdHub 是一个最小的技能注册表。启用 ClawdHub 后，agent 可以自动搜索技能并根据需要拉入新技能。

ClawdHub

聊天命令

在 WhatsApp/Telegram/Slack/Google Chat/Microsoft Teams/WebChat 中发送这些命令（组命令仅所有者可用）：

  • /status — 紧凑的会话状态（模型 + 令牌，可用时包括成本）
  • /new 或 /reset — 重置会话
  • /compact — 压缩会话上下文（摘要）
  • /think <level> — off|minimal|low|medium|high|xhigh（仅 GPT-5.2 + Codex 模型）
  • /verbose on|off
  • /usage off|tokens|full — 每回复使用页脚
  • /restart — 重启网关（组中仅所有者）
  • /activation mention|always — 组激活切换（仅组）

应用（可选）

仅网关就能提供出色的体验。所有应用都是可选的，并添加额外功能。

如果你计划构建/运行配套应用，请遵循以下平台运行手册。

macOS（Moltbot.app）（可选）

  • 网关和健康状况的菜单栏控制。
  • 语音唤醒 + 按下通话覆盖层。
  • WebChat + 调试工具。
  • 通过 SSH 进行远程网关控制。

注意：签名的构建需要 macOS 权限才能在重建后保持有效（参见 docs/mac/permissions.md）。

iOS 节点（可选）

  • 通过网桥作为节点配对。
  • 语音触发转发 + 画布表面。
  • 通过 moltbot nodes … 控制。

运行手册：iOS 连接。

Android 节点（可选）

  • 通过与 iOS 相同的网桥 + 配对流程配对。
  • 暴露画布、相机和屏幕捕获命令。
  • 运行手册：Android 连接。

Agent 工作区 + 技能

  • 工作区根目录：~/clawd（可通过 agents.defaults.workspace 配置）。
  • 注入的提示文件：AGENTS.md、SOUL.md、TOOLS.md。
  • 技能：~/clawd/skills/<skill>/SKILL.md。

配置

最小的 ~/.clawdbot/moltbot.json（模型 + 默认值）：

{
  agent: {
    model: "anthropic/claude-opus-4-5"
  }
}

完整配置参考（所有键 + 示例）。

安全模型（重要）

  • 默认：工具在主会话的主机上运行，因此当只有你时，agent 具有完全访问权限。
  • 组/频道安全：设置 agents.defaults.sandbox.mode: "non-main"以在每会话 Docker 沙箱中运行非主会话（组/频道）；然后 bash 在这些会话的 Docker 中运行。
  • **沙箱默认值：**允许列表 bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn；拒绝列表 browser、canvas、nodes、cron、discord、gateway。

详情：安全指南 · Docker + 沙箱 · 沙箱配置

WhatsApp

  • 链接设备：pnpm moltbot channels login（将凭据存储在 ~/.clawdbot/credentials 中）。
  • 通过 channels.whatsapp.allowFrom 允许谁可以与助手交谈。
  • 如果设置了 channels.whatsapp.groups，它会成为组允许列表；包含 "*" 以允许所有。

Telegram

  • 设置 TELEGRAM_BOT_TOKEN 或 channels.telegram.botToken（环境获胜）。
  • 可选：设置 channels.telegram.groups（带有 channels.telegram.groups."*".requireMention）；当设置时，它是组允许列表（包含 "*" 以允许所有）。还需要 channels.telegram.allowFrom 或 channels.telegram.webhookUrl。
{
  channels: {
    telegram: {
      botToken: "123456:ABCDEF"
    }
  }
}

Slack

  • 设置 SLACK_BOT_TOKEN + SLACK_APP_TOKEN（或 channels.slack.botToken + channels.slack.appToken）。

Discord

  • 设置 DISCORD_BOT_TOKEN 或 channels.discord.token（环境获胜）。
  • 可选：设置 commands.native、commands.text 或 commands.useAccessGroups，以及根据需要设置 channels.discord.dm.allowFrom、channels.discord.guilds 或 channels.discord.mediaMaxMb。
{
  channels: {
    discord: {
      token: "1234abcd"
    }
  }
}

Signal

  • 需要 signal-cli 和 channels.signal 配置部分。

iMessage

  • 仅 macOS；Messages 必须已登录。
  • 如果设置了 channels.imessage.groups，它会成为组允许列表；包含 "*" 以允许所有。

Microsoft Teams

  • 配置 Teams 应用 + Bot 框架，然后添加 msteams 配置部分。
  • 通过 msteams.allowFrom 允许谁可以交谈；通过 msteams.groupAllowFrom 或 msteams.groupPolicy: "open" 进行组访问。

WebChat

  • 使用 Gateway WebSocket；没有单独的 WebChat 端口/配置。

浏览器控制（可选）：

{
  browser: {
    enabled: true,
    color: "#FF4500"
  }
}

文档

当你通过入门流程并想要更深入的参考时，请使用这些内容。

高级文档（发现 + 控制）

运维和故障排除

深入探讨

工作区和技能

平台内部

Email 钩子（Gmail）

Molty

Moltbot 是为 Molty 构建的，一个太空龙虾 AI 助手。🦞 由 Peter Steinberger 和社区制作。

社区

参见 CONTRIBUTING.md 了解指南、维护者和如何提交 PR。 欢迎 AI/vibe 编码的 PR！🤖

特别感谢 Mario Zechner 的支持和 pi-mono。

感谢所有 clawtributors：