在 AI Agent 工具链层出不穷的当下，如何让同一个 Agent 助手在手机、电脑、不同通讯平台间无缝切换，始终是一个工程难题。Moltbot 给出的答案是：以 Node.js 为运行时基座，通过 Gateway WebSocket 控制平面统一调度多通道连接与多端节点，实现「本地优先、跨平台透明」的 Agent 运行时体验。本文将从架构设计、运行时依赖、通道路由与设备协同四个维度，拆解其工程实现的关键参数与配置要点。
Gateway 控制平面：单一 WebSocket 入口的工程取舍
Moltbot 的核心架构被称为 Gateway，这是一个运行在本地的 WebSocket 服务，默认监听 127.0.0.1:18789 端口。所有外部通道（WhatsApp、Telegram、Slack 等）、CLI 命令行工具、WebChat UI、macOS 菜单栏应用以及 iOS/Android 设备节点，都通过这个统一入口接入。这种设计的优势在于将连接管理、会话状态、工具调度集中在一处，避免了多进程间的状态同步复杂性；但同时也意味着 Gateway 本身成为单点故障源 —— 一旦服务中断，所有通道将同时离线。
为了保证服务持续运行，Moltbot 在安装时通过 moltbot onboard --install-daemon 命令将 Gateway 注册为系统级用户服务：在 macOS 上使用 launchd，在 Linux/Windows（WSL2）上使用 systemd。该守护进程在用户登录后自动启动，支持 moltbot gateway --port 18789 --verbose 的参数化启动方式。值得注意的是，Gateway 默认绑定在 loopback 接口（127.0.0.1），即使启用 Tailscale Serve 或 Funnel 进行远程访问，这一约束也不会改变 ——Moltbot 强制要求本地绑定，以防止意外暴露内部服务端口。
运行时依赖与版本约束
Moltbot 对运行时环境有明确的版本要求：Node.js 必须为 22 或更高版本。这一约束源于项目对现代 ES 模块特性、WebSocket API 稳定性以及 V8 引擎性能的综合考量。安装方式支持 npm、pnpm 或 bun 三种主流包管理器，推荐使用 pnpm 以获得更快的依赖解析速度。从源码构建时，项目使用 TypeScript，需要执行 pnpm ui:build 编译内置的 Web UI 组件，随后通过 pnpm build 生成生产环境的 dist 目录。
对于需要远程部署的场景，Moltbot 提供了 Docker 镜像与 Nix 配置两种容器化方案。Docker 部署时，容器内部会启动 Gateway 进程并暴露 WebSocket 端口，外部通道则通过环境变量注入认证凭据。Nix 模式则面向追求声明式配置的用户，支持通过 flakes 形式固化整个运行环境的依赖关系。
多通道路由架构：通道隔离与消息分发策略
Moltbot 目前支持 14 种即时通讯通道的原生接入，包括 WhatsApp（基于 Baileys 库）、Telegram（grammY）、Slack（Bolt）、Discord（discord.js）、Google Chat（Chat API）、Signal（signal-cli）、iMessage（imsg）、BlueBubbles、Microsoft Teams、Matrix、Zalo、Zalo Personal 以及 WebChat。每种通道都封装为独立的适配器模块，内部维护各自的 WebSocket 长连接或轮询机制。
通道路由遵循两个核心原则：来源隔离与策略可配置。对于私聊（DM）消息，默认采用配对模式（dmPolicy="pairing"），即未知发送者会收到一个简短的配对码，只有管理员通过 moltbot pairing approve <channel> <code> 确认后，消息才会被转交 Agent 处理。这种设计有效防止了垃圾消息攻击和 Prompt Injection 风险。若需要开放公聊入口，可将策略改为 dmPolicy="open" 并在 allowFrom 列表中加入通配符 "*"。
群组消息的处理更为复杂，涉及提及 gating、回复标签、每通道的消息分块策略等多重逻辑。Moltbot 通过 groupActivation 参数控制 Agent 在群聊中的唤醒方式：设为 mention 时只有被 @ 才会响应，设为 always 则持续监听。对于 Slack、Discord 等支持原生命令的平台，Moltbot 还支持斜杠命令（如 /status、/new、/compact），可以直接在聊天界面中触发 Agent 行为。
设备节点协同：macOS/iOS/Android 的能力暴露机制
除了云端 Gateway，Moltbot 还提供了配套的原生应用以访问设备本地能力。macOS 应用以菜单栏常驻程序形式运行，提供 Voice Wake（语音唤醒）、Push-to-Talk（按键说话）、Talk Mode（持续对话 Overlay）以及远程 Gateway 控制功能。macOS 应用可以切换为「节点模式」，通过 WebSocket 向 Gateway 汇报自身的能力列表与权限映射（通过 node.list 与 node.describe 方法）。
当 Gateway 接收到需要本地执行的请求时（如运行系统命令、拍摄照片、录制屏幕），会通过 node.invoke 将任务下发到对应设备节点。例如 system.run 工具会在目标设备上执行 bash 命令并返回 stdout/stderr/exit code，若命令涉及屏幕录制或系统通知，会自动检查并要求相应的 TCC（Transparency, Consent, and Control）权限。camera.snap、screen.record、location.get 等设备专属工具遵循相同的远程调用协议，使得 Agent 可以在不了解底层平台差异的情况下，统一调用「拍照」「录屏」「获取位置」等跨平台功能。
iOS 与 Android 节点通过 Bridge 协议与 Gateway 配对，配对流程与 macOS 节点类似。配对成功后，移动端会暴露 Canvas 绘图表面、摄像头快门、屏幕录制以及可选的 SMS 发送能力。移动节点的典型使用场景包括：在手机上拍摄实物照片供 Agent 分析、通过语音唤醒在房间另一端与 Agent 对话、以及在 Android 上接收 SMS 验证码并自动填入表单。
安全模型与沙箱隔离策略
Moltbot 的安全模型建立在「本地信任」与「通道隔离」两个维度上。默认情况下，main 会话（私聊窗口）拥有完整的工具执行权限 ——Agent 可以调用浏览器、运行系统命令、访问文件系统，这与其作为「个人助理」的定位一致。但对于群聊、频道等多用户场景，Moltbot 提供了可选的 Docker 沙箱隔离：agents.defaults.sandbox.mode: "non-main" 会让非主会话在独立容器中运行，所有文件操作和命令执行都被限制在容器内部。
沙箱模式下，工具白名单需要显式配置：默认允许 bash、process、read、write、edit、sessions_list、sessions_history、sessions_send、sessions_spawn，而 browser、canvas、nodes、cron、discord、gateway 等敏感工具则默认被拒绝。这种细粒度的权限控制使得在团队协作场景中部署 Moltbot 成为可能，同时避免了恶意用户利用 Agent 执行未授权操作的风险。
模型选择与故障转移机制
Moltbot 支持多模型接入，官方推荐 Anthropic Pro/Max（100K/200K 上下文）配合 Opus 4.5 模型，以获得最佳的长上下文处理能力和 Prompt Injection 抗性。同时，项目也原生支持 OpenAI 的 ChatGPT 与 Codex 系列模型，并提供了 OAuth 与 API Key 两种认证方式的灵活切换。
模型配置通过 ~/.clawdbot/moltbot.json 文件管理，最小配置仅需指定 agent.model 字段。Moltbot 内置了模型故障转移（failover）机制：当主模型因限流或网络问题不可用时，系统会自动切换到配置的备用模型，确保 Agent 对话不中断。这一机制对于生产环境部署尤为重要，因为大模型 API 的可用性波动往往超出应用层控制范围。
远程访问与 Tailscale 集成
尽管 Gateway 默认绑定本地端口，Moltbot 仍然提供了安全的远程访问方案。通过 Tailscale 的 Serve（仅 tailnet 内可访问）或 Funnel（公网可访问）功能，用户可以在保持 Gateway 本地绑定的情况下，通过 HTTPS 暴露 WebSocket 控制平面与 Web UI。启用方式为设置 gateway.tailscale.mode 为 serve 或 funnel，其中 Funnel 模式强制要求设置密码认证（gateway.auth.mode: "password"）以防止未授权访问。
对于不便使用 Tailscale 的环境，Moltbot 还支持 SSH 隧道方案：Gateway 主机与客户端之间建立 SSH 端口转发，WebSocket 流量通过加密隧道传输。这种方案的优势在于不依赖额外的网络虚拟化软件，但配置复杂度略高，需要手动管理 SSH 密钥与端口映射。
运维工具与健康检查
Moltbot 提供了 moltbot doctor 命令用于健康检查与配置诊断，该命令会扫描当前的通道配置、DM 策略设置、模型凭据有效性以及潜在的权限问题，并以结构化报告形式输出。对于升级场景，运行 moltbot update --channel stable|beta|dev 可以在不同发布通道间切换：stable 为正式发布版本，beta 为预发布版本，dev 则对应主分支的最新构建。
日志系统默认输出到标准输出与旋转文件，支持通过 moltbot gateway 的 --verbose 参数调整日志级别。在排查通道连接问题时，开启详细日志是定位根因的关键步骤。
总体而言，Moltbot 的跨平台 Agent 运行时设计围绕 Gateway 中心化控制平面展开，通过 WebSocket 统一接入多通道适配器与多端设备节点，在保持架构简洁性的同时提供了灵活的扩展能力。其安全模型兼顾了个人助理场景的高权限需求与多用户场景的隔离要求，运维工具链也趋于完善。对于希望构建本地化、私密化 AI 助手的开发者而言，Moltbot 的架构设计提供了值得参考的工程范式。
资料来源：
- Moltbot GitHub 仓库：https://github.com/moltbot/moltbot
- Moltbot 官方文档：https://docs.molt.bot/