bitterbot-desktop

环境要求

• Node.js ≥ 22
• 包管理器 pnpm（可用 corepack 启用）
• 系统依赖：ffmpeg、ripgrep、jq 等（由 scripts/setup-deps.sh 安装）
• Playwright Chromium（浏览器自动化用）
• Windows 用户需使用 WSL2，并克隆到 Linux 文件系统（如 ~/bitterbot-desktop）

安装与启动步骤

1. 1启用 pnpm

   项目指定使用 pnpm。若本机没有 pnpm，用 corepack 启用，失败则改用 npm 全局安装。

   corepack enable pnpm || npm install -g pnpm

   复制

2. 2克隆并进入仓库

   把 bitterbot-desktop 源码克隆到本地并进入项目根目录，后续命令都在该目录执行。

   git clone https://github.com/Bitterbot-AI/bitterbot-desktop.git && cd bitterbot-desktop

   复制

3. 3安装系统依赖

   执行仓库自带脚本安装 ffmpeg、ripgrep、jq 等系统级依赖，需要系统包管理器权限。

   bash scripts/setup-deps.sh

   复制

4. 4安装项目依赖

   在项目根目录安装 TypeScript 项目依赖，耗时较长，请保持网络畅通。

   pnpm install

   复制

5. 5安装浏览器内核

   安装 Playwright 的 Chromium 及系统依赖，供智能体做网页浏览自动化使用。

   pnpm exec playwright install --with-deps chromium

   复制

6. 6运行引导向导

   向导会依次配置模型鉴权(API Key)、记忆嵌入、网络搜索、渠道、钱包和工作区，并自动启动网关与 Control UI、打开浏览器。

   pnpm bitterbot onboard

   复制

7. 7访问控制台

   向导完成后 Bitterbot 已在运行，浏览器访问该地址即可聊天、查看梦境、管理技能；不要在服务器上改端口。

8. 8手动再次启动

   若跳过了向导的自动启动，用此命令启动网关（自带 Control UI）。首次运行会自动构建 dist/entry.js 并准备 UI，无需单独 pnpm build。

   pnpm start:all

   复制

关键配置

如何确认成功

浏览器打开 http://127.0.0.1:19001 能看到 Bitterbot Control UI，即网关与 UI 已正常运行。

常见问题

注意事项

• Control UI 与网关同源同端口（19001），在运行网关的本机直接打开即可，无需手动配置令牌。
• 首次 pnpm start:all 会自动构建 dist/entry.js 并准备 Control UI，不需要单独执行 pnpm build。
• desktop/.env 只是 pnpm dev:all 开发模式的覆盖配置，正式使用不需要。
• 项目为本地优先设计，记忆与数据保存在本地，隐私性更强。