安装与更新策略

适用范围

当你需要在新机器上完成配置，或希望“升级到最新版本但不影响个人定制”时，用这页。

Last updated: 2026-01-01

TL;DR

• 个性化内容放在仓库之外：~/clawd（workspace）+ ~/.moltbot/moltbot.json（config）。
• 稳定路径：安装 macOS 应用，让应用管理并运行内置网关。
• 开发/前沿路径：你在终端用 pnpm gateway:watch 跑网关热重载，macOS 应用用 Local 模式连接到现有网关。

前置条件（从源码运行时）

• Node >=22
• pnpm
• Docker（可选；仅用于容器化/端到端测试）：/en/docs/install/docker/

个性化策略（让升级不伤）

如果你既想“完全按自己习惯定制”，又希望升级省心，把定制收敛到两个地方：

• 配置：~/.moltbot/moltbot.json（JSON/JSON5-ish）
• 工作区：~/clawd（skills、prompts、memories；建议做成私有 git 仓库）

首次初始化：

moltbot setup

如果你在仓库里运行，使用本地 CLI 入口：

moltbot setup

如果你还没全局安装 CLI，可用 pnpm moltbot setup。

稳定路径（macOS 应用优先）

1. 安装并启动 Moltbot.app（菜单栏）。
2. 完成权限/初始化清单（TCC 弹窗）。
3. 确认网关为 Local 且已运行（由应用管理）。
4. 绑定聊天入口（例如 WhatsApp）：

moltbot channels login

5. 健康检查：

moltbot health

如果你的构建中没有 onboarding：

• 先跑 moltbot setup，再跑 moltbot channels login，最后手动启动网关（moltbot gateway）。

开发/前沿路径（终端里跑网关）

目标：开发 TypeScript 网关，获得热重载，同时让 macOS 应用 UI 连接到现有网关。

0)（可选）macOS 应用也从源码运行

如果你希望 macOS 应用也跟随最新代码：

./scripts/restart-mac.sh

1) 启动开发网关

pnpm install
pnpm gateway:watch

gateway:watch 会以 watch 模式运行网关，并在 TypeScript 变更时自动重载。

2) 让 macOS 应用连接到你的网关

在 Moltbot.app 里：

• Connection Mode：选择 Local

应用会在已配置端口上连接运行中的网关。

3) 验证

• 应用内网关状态应显示：Using existing gateway …
• 或用 CLI：

moltbot health

常见坑

• 端口不一致：网关 WS 默认是 ws://127.0.0.1:18789；应用与 CLI 必须使用同一端口。
• 状态文件在哪里：
  • Credentials：~/.moltbot/credentials/
  • Sessions：~/.moltbot/agents/<agentId>/sessions/
  • Logs：/tmp/moltbot/

升级（不破坏你的设置）

• 把 ~/clawd 与 ~/.moltbot/ 当作“你的资产”，不要把个人 prompts/config 写进 moltbot 仓库。
• 源码升级：git pull +（lockfile 变更时）pnpm install，继续用 pnpm gateway:watch。

Linux（systemd user service）

Linux 安装使用 systemd user service。默认情况下，systemd 会在用户注销/空闲时停止 user services，导致网关退出。 向导会尝试帮你打开 lingering（可能会请求 sudo）。如果仍未开启，可以手动执行：

sudo loginctl enable-linger $USER

如果你需要 always-on 或多用户服务器，更建议用 system service（不需要 lingering）。相关说明见：/docs/gateway/。

相关文档

• 网关运行手册：/docs/gateway/（flags、守护、端口）
• 网关配置：/docs/gateway/configuration/（schema 与示例）
• Discord：/docs/channels/discord/；Telegram：/docs/channels/telegram/（reply tags 与 replyToMode）
• Moltbot 助手配置：/en/docs/start/clawd/
• macOS 应用：/en/docs/platforms/macos/