Moltbot

Moltbot Gateway 开发

本指南适合想要使用热重载编辑 TypeScript Gateway 或运行前沿版本的开发者。

太长不看

# 终端 1：启动开发 Gateway pnpm install pnpm gateway:watch # 终端 2（可选）：从源码运行 macOS 应用 ./scripts/restart-mac.sh # 在 Moltbot.app 中：将连接模式设为「本地」 # 验证： moltbot health

何时使用此工作流程

如果你有以下需求，请选择 Gateway 开发工作流程：

  • 想要为 Moltbot 做贡献
  • 需要编辑 TypeScript 时的热重载
  • 想要运行最新的未发布代码
  • 正在调试 Gateway 问题

一般使用请参阅 macOS 应用安装

环境要求

  • Node.js >= 22
  • pnpm
  • Git
  • (可选) Moltbot.app 已安装

分步指南

1. 克隆仓库

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

2. 安装依赖

pnpm install

3. 启动开发 Gateway

pnpm gateway:watch

此命令会：

  • 编译 TypeScript Gateway
  • 在 ws://127.0.0.1:18789 启动 WebSocket 服务器
  • 监听文件更改并自动重载

你应该看到如下输出：

Gateway started on ws://127.0.0.1:18789 Watching for changes...

4. 连接 macOS 应用（可选）

如果你想使用 macOS 应用界面连接开发 Gateway：

  1. 打开 Moltbot.app
  2. 点击菜单栏图标
  3. 进入「设置」→「连接」
  4. 将连接模式设为「本地」

应用现在会连接到你运行的 Gateway。你应该看到：「Using existing gateway on port 18789...」

5.（可选）从源码运行 macOS 应用

如需完整的前沿开发体验，也可以从源码运行 macOS 应用：

./scripts/restart-mac.sh

6. 验证设置

moltbot health

所有检查应该通过。Gateway 状态应显示你的开发实例。

开发命令

命令说明
pnpm gateway:watch启动带热重载的 Gateway
pnpm gateway:build构建生产版 Gateway
pnpm test运行测试套件
pnpm lint运行代码检查
pnpm typecheckTypeScript 类型检查

Gateway 配置

端口配置

默认端口是 18789。要更改它：

# 通过环境变量 GATEWAY_PORT=18790 pnpm gateway:watch # 或在 ~/.clawdbot/moltbot.json 中 { "gateway": { "port": 18790 } }
重要提示：保持 macOS 应用和命令行使用相同端口，否则它们无法通信。

调试模式

启用详细日志：

DEBUG=moltbot:* pnpm gateway:watch # 或针对特定模块： DEBUG=moltbot:gateway,moltbot:channels pnpm gateway:watch

架构概述

┌─────────────────────┐ WebSocket ┌─────────────────────┐ │ Moltbot.app │◄──────────────────►│ Gateway │ │ (Menu Bar UI) │ :18789 │ (TypeScript) │ └─────────────────────┘ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Channels │ │ (WhatsApp, TG...) │ └─────────────────────┘

Gateway 是核心引擎，它：

  • 管理 AI 模型连接
  • 处理渠道集成
  • 处理消息并执行技能
  • 存储会话和记忆

常见问题

端口已被占用
# 查找占用端口的进程 lsof -i :18789 # 终止它或使用其他端口 GATEWAY_PORT=18790 pnpm gateway:watch
应用显示「已断开」
  1. 确保 Gateway 正在运行（pnpm gateway:watch）
  2. 检查应用是否设为「本地」模式
  3. 验证端口一致
热重载不工作

检查终端中的 TypeScript 错误。语法错误会阻止重载。

更新开发环境

# 拉取最新更改 git pull # 更新依赖（如果 lockfile 有变化） pnpm install # 重启 Gateway pnpm gateway:watch
将 ~/clawd 和 ~/.clawdbot/ 用于你的个人内容。不要将自定义提示词或配置放在 moltbot 仓库中 - git pull 时会丢失。

下一步

配置参考

了解所有配置选项

查看指南

贡献指南

如何提交 PR

查看指南

Gateway 运维手册

高级 Gateway 操作

查看指南

相关内容

Gateway 开发模式 | Moltbot 安装指南