快速开始 · aibuddy Docs

先选择运行宿主

aibuddy 提供两条开发路径。Web 适合验证托管、多用户和后台执行；Desktop 适合验证本地数据、本机文件与 Shell。两者共享 @aibuddy/core 中的任务语义和 Agent 行为，不要求同时启动。

如果要验证	选择	运行时组成
Web 前端、API、队列或多用户能力	Web	浏览器、Hono Server、PostgreSQL，以及按配置启用的 Redis/BullMQ
Electron、本地数据或本机执行	Desktop	Renderer、Electron Main、SQLite 与本地 Node sandbox

本页的目标不是搭建生产环境，而是完成一项任务，并确认回复、工具活动和最终状态均可观察。生产部署、跨实例恢复和远程沙箱不在首次运行范围内。

两条路径共享同一组基础准备

仓库要求 Node.js >=24 <25，并通过 Corepack 固定 pnpm 11.14.0。Web 还需要 PostgreSQL 15 或更高版本；Redis 只在验证 BullMQ、Schedule、跨实例事件和可恢复流时需要。

git clone https://github.com/lib4x/aibuddy.git
cd aibuddy
corepack enable
corepack prepare [email protected] --activate
pnpm install

安装完成后，只执行下面的一条平台路径。

Web 以最小服务集运行第一项任务

复制 Server 配置：

cp apps/server/.env.example apps/server/.env

首次本地运行至少需要数据库、鉴权密钥和一个可用的模型入口。下面使用 inline queue，因而不要求先启动 Redis：

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/aibuddy
BETTER_AUTH_SECRET=replace-with-a-random-secret-at-least-32-characters
BASE_URL=http://localhost:8001
AI_GATEWAY_API_KEY=your-ai-gateway-key
SANDBOX_TYPE=node
JOB_QUEUE_MODE=inline

创建数据库并初始化 schema 与演示数据：

createdb aibuddy
pnpm --filter=@aibuddy/server db:setup

启动 Web、API 和 worker 开发进程：

pnpm dev:app

浏览器访问 http://localhost:8000。可以注册新账号，也可以使用 seed 创建的演示账号 [email protected] / admin@123。创建一项 Task，要求 Agent 读取或生成一个简单文件，以便同时验证消息流和工具执行。

JOB_QUEUE_MODE=inline 只适合最小开发路径。需要验证队列重试、Schedule、跨实例通知或可恢复流时，应配置 REDIS_URL，并使用 BullMQ 路径。

Desktop 在本机运行同一任务模型

复制 Desktop 配置并启动应用：

cp apps/desktop/.env.example apps/desktop/.env
pnpm dev:desktop

开发环境中的 ELECTRON_RENDERER_URL 应指向 http://localhost:8002。首次启动按以下顺序完成初始化：

在“设置 → API Keys”中添加并验证提供商密钥。
为该提供商添加至少一个模型。
创建 Task，并要求 Agent 读取或生成一个简单文件。

Desktop 在 Electron Main 中内联执行 Agent turn，不依赖 Server、PostgreSQL、Redis 或 BullMQ。任务、对话和模型配置保存在本地 SQLite，提供商凭证由 Electron safeStorage 保护。

三个信号共同证明运行成功

不要只以“界面出现一段回复”作为成功标准。首次运行应同时满足：

回复持续到达：界面能够看到流式文本，而不是一次无状态请求。
工具活动可检查：任务需要工具时，界面能够显示调用及其结果。
任务状态明确收敛：Task 最终进入完成、等待、取消或失败中的明确状态，而不是永久停留在运行中。

如果只需要验证模型连接，可以发送普通问题；如果要验证完整任务路径，应让 Agent 操作一个可安全丢弃的测试文件，并检查文件内容是否与回复一致。

故障应按所在边界排查

现象	优先检查
Web 页面可打开，但 API 返回 404	`apps/server` 是否运行在 `localhost:8001`
Web 登录失败或持续重定向	`BASE_URL` 与鉴权密钥
Web 启动时数据库报错	PostgreSQL、`DATABASE_URL` 与 `db:setup`
第一条消息返回模型鉴权错误	Gateway 或提供商密钥，以及所选模型
Desktop 停留在初始设置	是否同时存在已验证 API Key 和至少一个用户模型
Desktop 白屏	`ELECTRON_RENDERER_URL` 是否指向 `localhost:8002`
Agent 回复但工具不可用	`SANDBOX_TYPE`、任务工作区与对应进程日志
Task 长期保持运行中	Server/Worker 或 Electron Main 日志

首次运行不代表平台能力完全对等

Web 与 Desktop 共享任务模型，不共享全部基础设施能力。Web 的多用户身份、BullMQ、跨实例事件与对象存储依赖服务端配置；Desktop 使用设备端身份、本地数据库和本机执行。Desktop 当前尚未接通 MCP provider；Node sandbox 也直接运行在宿主进程树中，不等同于远程隔离沙箱。

这些差异不会改变 Task、上下文、工具事件和最终状态的基本语义，但会改变数据保存位置、可用能力和故障恢复范围。