Moltbot 是一款功能强大的个人 AI 助手框架，它通过一个中心化的“网关”（Gateway）服务，连接了各种聊天渠道（如 WhatsApp, Telegram）和大型语言模型，同时提供了网页仪表盘（Dashboard）和终端界面（TUI）等多种交互方式。这篇教程将详细介绍如何下载、安装并开始使用 Moltbot。
系统环境准备
在开始安装之前，需要确保系统满足一些基本要求。Moltbot 主要设计运行在 macOS、Linux 或通过 WSL2 (Windows Subsystem for Linux 2) 运行的 Windows 系统上。
核心的依赖是 Node.js。Moltbot 要求 Node.js 的版本必须是 22 或更高。可以通过在终端运行以下命令来检查当前系统中安装的 Node.js 版本：
node -v
如果系统尚未安装 Node.js，或者版本低于 22，需要先进行安装或升级。推荐从 Node.js 官方网站下载安装包，或者使用 nvm (Node Version Manager) 这类工具来管理多个 Node.js 版本，这样可以更灵活地切换。
除了 Node.js，如果选择从源码进行编译安装，还需要安装 pnpm 包管理器。但对于大多数用户而言，使用官方推荐的安装脚本就足够了，这种方式会自动处理大部分依赖问题。
快速安装 Moltbot
对于初次接触 Moltbot 的用户，最简单、最推荐的安装方式是使用官方提供的一键安装脚本。这个脚本会自动检测操作系统，检查并安装必要的依赖（如 Node.js），最后完成 Moltbot 的全局安装。
macOS 和 Linux 系统
在 macOS 或 Linux 系统的终端中，执行以下命令即可开始安装：
curl -fsSL https://molt.bot/install.sh | bash
这条命令会从 molt.bot 服务器下载安装脚本，并通过管道 | 交给 bash 来执行。脚本运行过程中，它会检查 Node.js 版本，如果版本不符合要求，它会尝试使用系统包管理器（如 macOS 的 Homebrew）来安装或升级。随后，它会使用 npm 将 Moltbot 安装到全局环境中。
Windows 系统
对于 Windows 用户，需要使用 PowerShell 来执行安装。请以管理员权限打开 PowerShell，然后运行以下命令：
iwr -useb https://molt.bot/install.ps1 | iex
iwr (Invoke-WebRequest) 负责下载 PowerShell 安装脚本，而 iex (Invoke-Expression) 则会执行下载的脚本内容。这个过程与在 Linux 上的体验类似，脚本会自动处理环境配置和安装。
首次启动与配置向导
安装脚本执行完毕后，通常会自动启动一个名为 onboard（上手）的配置向导。这个向导是为新用户设计的，它会引导完成一些关键的初始设置。
如果安装脚本因为某些原因没有自动启动向导，或者在安装时选择了跳过，可以随时手动运行它：
moltbot onboard --install-daemon
moltbot onboard 命令会提出一系列问题，帮助你生成初始的配置文件。这些配置包括设置 Gateway 的认证令牌、选择默认的 AI 模型等。
--install-daemon 参数是一个非常重要的选项。它会告诉 Moltbot 将其核心服务——Gateway——安装成一个系统后台守护进程（在 macOS 上是 launchd 服务，在 Linux 上是 systemd 服务）。这样做的好处是，Gateway 会在系统启动时自动运行，并且即使用户退出了终端会话，服务也能保持在线，确保 AI 助手始终可用。
强烈建议在首次配置时加上 --install-daemon 参数，这能极大地简化后续的使用和管理。
在向导过程中，你需要提供以下关键信息：
- AI 模型授权：
Moltbot 本身不包含 AI 模型，它需要连接到外部的 AI 服务，如 Anthropic (Claude) 或 OpenAI (ChatGPT)。你需要准备好相应服务的订阅和 API 密钥或通过 OAuth 授权（笔者这里用的是 Google Gemini CLI 授权）。
2. 渠道配置（可以跳过）：选择你希望用来与 Moltbot 交流的聊天工具，并根据提示完成配对。这里都是海外平台的，可以直接跳过。
后面会问你要不要 skills，无脑选 Yes 就行（先按空格键再按 Enter 回车键），或者直接跳过。
后面的配置看着来，Hooks 的话可以勾选（先按空格键再按 Enter 回车键）。
完成向导后，你的第一个个人 AI 助理就基本部署完成了。它会问你要不要打开一个 Web UI，选择它即可：
最后我们就会得到这个可视化界面（地址通常是： http://127.0.0.1:18789/chat ）：
检查安装状态
完成安装和初始配置后，有几个命令可以用来验证 Moltbot 是否已正确安装并正在运行。
诊断工具 Doctor
moltbot doctor 是一个非常有用的诊断命令。它会检查系统的配置、文件权限、服务状态以及其他可能影响 Moltbot 运行的因素。
moltbot doctor
运行这个命令后，它会输出一份健康检查报告。如果发现任何问题，比如配置文件格式过时、权限不正确等，它通常会给出修复建议，有时甚至会自动进行修复。在遇到问题或更新版本后，运行 moltbot doctor 应该是首选的排错步骤。
查看 Gateway 状态
Gateway 是 Moltbot 的核心服务，所有的数据和指令都通过它来中转。可以使用 moltbot status 来快速查看 Gateway 服务的当前状态。
moltbot status
这个命令会显示 Gateway 服务是否正在运行、监听的端口号以及进程 ID 等信息。
如果想获取更详细的健康状况，比如连接的模型、启用的通道等，可以使用 moltbot health 命令。
moltbot health
这个命令会直接与正在运行的 Gateway 通信，并返回一份实时的健康报告，内容比 status 更为丰富。
多种安装方式的选择
除了推荐的快速安装脚本，Moltbot 也提供了其他几种安装方式，以满足不同用户的需求。这里对几种主要方式进行对比，方便根据自己的情况做出选择。
| 安装方式 | 适用人群 | 优点 | 缺点 |
|---|---|---|---|
| 安装脚本 (推荐) | 大多数用户，尤其是初学者 | 自动化程度高，能自动处理环境依赖，一键完成安装和基础配置。 | 灵活性相对较低，自定义安装选项需要通过脚本参数实现。 |
| 手动全局安装 | 熟悉 Node.js 和 npm 的用户 | 控制力更强，可以精确指定安装的版本，过程透明。 | 可能需要手动解决环境问题，如 PATH 变量配置、依赖冲突等。 |
| 从源码安装 | 开发者、贡献者 | 可以获取最新的代码，便于进行二次开发、修改和调试。 | 步骤最复杂，需要手动安装 Git 和 pnpm，并自行编译项目。 |
手动全局安装
如果你的系统已经配置好了 Node.js >= 22 的环境，并且倾向于手动控制安装过程，可以直接使用 npm 或 pnpm 进行全局安装。
使用 npm 的命令如下：
npm install -g moltbot@latest
-g 参数表示全局安装，@latest 表示安装最新的稳定版本。
在某些系统环境下，尤其是在 macOS 上通过 Homebrew 安装了 libvips 库时，npm 在安装 sharp 这个图像处理依赖包时可能会遇到编译失败的问题。此时，可以设置一个环境变量来强制使用预编译好的二进制文件，绕过本地编译：
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g moltbot@latest
手动安装完成后，别忘了运行配置向导并安装守护进程：
moltbot onboard --install-daemon
从源码安装
对于希望参与开发或需要使用最前沿功能的开发者，可以从 GitHub 克隆项目仓库并从源码进行安装。
首先，克隆仓库到本地：
git clone https://github.com/moltbot/moltbot.git
cd moltbot
进入项目目录后，使用 pnpm 安装所有依赖：
pnpm install
然后，编译前端界面和后端代码：
pnpm ui:build
pnpm build
完成编译后，就可以像全局安装一样使用 moltbot 命令了。同样，需要运行配置向导：
moltbot onboard --install-daemon
解决 command not found 问题
在手动通过 npm 全局安装包后，一个常见的问题是在终端里输入 moltbot 命令时，系统提示 command not found (命令未找到)。
这个问题通常是因为 npm 全局安装目录的 bin 文件夹没有被添加到系统的 PATH 环境变量中。PATH 环境变量是一个路径列表，操作系统会按照这个列表去查找可执行文件。
可以通过以下步骤来诊断和解决这个问题。首先，确认 npm 的全局安装路径：
npm prefix -g
这个命令会输出一个路径，例如在 macOS/Linux 上可能是 /usr/local 或 ~/.npm-global，在 Windows 上可能是 %AppData%\npm。npm 全局安装的可执行文件都存放在这个路径下的 bin 目录里。
接下来，查看当前的 PATH 环境变量：
echo "$PATH"
检查 echo "$PATH" 的输出中是否包含了 $(npm prefix -g)/bin 这个路径。如果没有，就需要手动将它添加进去。
在 macOS 或 Linux 上，可以编辑 ~/.zshrc (如果使用 zsh) 或 ~/.bashrc (如果使用 bash)，在文件末尾添加以下这行：
export PATH="$(npm prefix -g)/bin:$PATH"
这行代码的作用是将 npm 的全局 bin 目录添加到 PATH 变量的最前面。保存文件后，需要重新打开一个新的终端窗口，或者执行 source ~/.zshrc (或 source ~/.bashrc) 来让改动立即生效。之后，moltbot 命令应该就可以被正常识别了。
使用 Moltbot 的核心界面
Moltbot 提供了两种主要的交互界面：基于浏览器的 Dashboard (控制台) 和基于终端的 TUI (文本用户界面)。两者都通过 WebSocket 连接到在后台运行的 Gateway 服务。
管理 Gateway 服务
Gateway 是 Moltbot 的心脏，负责处理所有任务。在将其安装为守护进程后，它会开机自启。但有时也需要手动管理它。
可以使用以下命令来控制 Gateway 服务：
- 安装 Gateway:
moltbot gateway install - 启动 Gateway:
moltbot gateway start（这个若用不了用moltbot gateway） - 停止 Gateway:
moltbot gateway stop - 重启 Gateway:
moltbot gateway restart - 卸载 Gateway:
moltbot gateway uninstall - 查看 Gateway 状态:
moltbot gateway status
如果需要查看 Gateway 的实时日志输出，可以使用 logs 命令：
moltbot logs --follow
--follow 参数会让命令持续输出新的日志，这对于调试问题非常有用。
使用 Dashboard (Web UI)
Dashboard 是功能最全面的图形化管理界面，推荐大多数用户使用。通过它，可以进行聊天、管理通道、配置技能、编辑配置文件等几乎所有操作。
打开 Dashboard 非常简单，只需在终端运行（前提是已启动 Gateway）：
moltbot dashboard
这个命令会做两件事：
- 生成一个包含临时认证令牌的 URL。
- 尝试在默认浏览器中打开这个 URL。
URL 的格式通常是 http://127.0.0.1:18789/?token=...。其中 127.0.0.1:18789 是 Gateway 默认监听的本地地址和端口，token 是用于安全认证的令牌。首次访问时，Dashboard 会将这个令牌保存在浏览器的 localStorage 中，后续访问就不再需要手动输入了。
如果看到 "unauthorized" (未授权) 的错误，通常意味着连接时没有提供正确的令牌。再次运行 moltbot dashboard 获取一个新的链接即可。
Dashboard 界面直观易用，左侧是功能导航，包括聊天、通道、配置、日志等模块。在这里可以直观地看到 Moltbot 的运行状态，并进行各种设置。
使用 TUI (终端界面)
对于喜欢在终端里工作的用户，Moltbot 提供了功能强大的 TUI。
在 Gateway 正在运行的情况下，打开一个新的终端窗口，执行以下命令即可启动 TUI：
moltbot tui
TUI 会连接到本地的 Gateway，并提供一个类似聊天软件的界面。你可以在底部的输入框中输入消息，按回车发送。AI 的回复会实时显示在聊天记录中。
TUI 也支持丰富的快捷键和斜杠命令 (/)，让操作更高效。例如：
- 输入
/help可以查看所有可用的命令。 - 输入
/session可以切换或创建新的聊天会话。 - 输入
/model可以查看和切换当前会话使用的 AI 模型。 - 按
Ctrl+C两次或输入/exit可以退出 TUI。
TUI 是一个轻量级但功能完备的客户端，特别适合在服务器或无图形界面的环境下使用 Moltbot。
更新 Moltbot
Moltbot 目前仍在快速迭代中，保持更新可以获得最新的功能和 Bug 修复。
推荐的更新方式
最简单、最安全的更新方式是重新运行官网的安装脚本。
curl -fsSL https://molt.bot/install.sh | bash
这个脚本足够智能，它会检测到已有的安装，并执行升级操作而不是全新安装。它会使用 npm install -g moltbot@latest 来获取最新版本，并根据需要运行 moltbot doctor 来迁移配置和检查系统状态。
为了避免升级后再次弹出初始配置向导，可以添加 --no-onboard 标志：
curl -fsSL https://molt.bot/install.sh | bash -s -- --no-onboard
手动更新
如果你是通过 npm 手动安装的，也可以直接使用 npm 命令来更新：
npm i -g moltbot@latest
i 是 install 的简写。这条命令会把全局安装的 moltbot 包更新到 npm 仓库中最新的 latest 版本。
更新完成后，强烈建议运行一次 moltbot doctor 来确保所有配置和依赖都是兼容的：
moltbot doctor
最后，重启 Gateway 服务以应用更新：
moltbot gateway restart
使用 moltbot update 命令
Moltbot 还内置了一个 update 命令，它提供更精细的更新控制，尤其适合从源码安装的用户。
moltbot update
对于源码安装，这个命令会自动拉取最新的代码、安装依赖、重新编译，并重启 Gateway。对于 npm 安装，它会尝试调用 npm 来完成更新。
这个命令还支持切换更新通道，例如切换到测试版 (beta) 或开发版 (dev)：
moltbot update --channel beta
对于大多数用户来说，保持在默认的稳定 (stable) 通道并使用安装脚本进行更新是最佳实践。
通过本教程，你应该已经成功安装了 Moltbot，并了解了它的基本使用方法。现在，可以打开 Dashboard，开始探索 Moltbot 的强大功能，将它打造成属于你自己的个性化 AI 助手了。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、API 调试、API 设计、API 测试、API Mock、自动化测试等功能于一体的 API 管理工具，Apifox 可以说是开发者提升效率的必备工具之一。
如果你正在开发项目需要进行接口调试，不妨试试 Apifox。注册过程非常简单，你可以直接在这里注册使用。
注册成功后可以先看看官方提供的示例项目，这些案例都是经过精心设计的，能帮助你快速了解 Apifox 的主要功能。
使用 Apifox 的一大优势是它完全兼容 Postman 和 Swagger 数据格式，如果你之前使用过这些工具，数据导入会非常方便。而且它的界面设计非常友好，即使是第一次接触的新手也能很快上手，快去试试吧！
