文档
开始使用
安装与更新策略

安装与更新策略

适用范围

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

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
  1. 健康检查：
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）。相关说明见：/zh-cn/docs/gateway/。

相关文档

  • 网关运行手册：/zh-cn/docs/gateway/（flags、守护、端口）
  • 网关配置：/zh-cn/docs/gateway/configuration/（schema 与示例）
  • Discord：/zh-cn/docs/channels/discord/；Telegram：/zh-cn/docs/channels/telegram/（reply tags 与 replyToMode）
  • Moltbot 助手配置：/en/docs/start/clawd/
  • macOS 应用：/en/docs/platforms/macos/
Moltbot 的传说 🦞📖快速开始