📌 项目简介

OpenBot 是一个 AI 代理平台，每个 Bot 都拥有自己独立的容器化环境（包括浏览器、工作空间和工具）。所有操作都通过一个策略网关执行，该网关会在操作前进行决策、记录审计日志，并支持人工接管。您可以使用任何支持 AG-UI 协议的代理框架（如 LangGraph, Mastra, CrewAI 等）。

重要提示：

  • 这是一个模板项目，用于克隆和定制，而非即拿即用的产品。
  • 目前处于Alpha阶段，正在积极开发中。
  • 运行在您自己的机器上，所有数据默认存储在本地 PostgreSQL 数据库中。

⚙️ 系统要求

在开始前，请确保您的系统已安装：

  • Docker：用于运行 PostgreSQL 数据库和内置的 Bot 服务。
  • Bun 1.3+：用于运行应用和 API 服务器。
  • 一个 CopilotKit Intelligence 项目和许可证：提供对话记忆和持久化功能。有免费套餐可用，也支持自托管。
  • 一个模型 API 密钥：例如 OpenAI API Key。

🚀 快速启动 (本地开发)

这是项目官方推荐的最快运行方式。

第 1 步：克隆仓库并创建环境文件

1
2
3
git clone https://github.com/CopilotKit/OpenBot.git
cd OpenBot
cp .env.example .env

第 2 步：获取并配置 CopilotKit Intelligence 凭证

  1. 在终端执行以下命令登录并选择项目：

    1
    2
    npx --yes copilotkit@latest login
    npx --yes copilotkit@latest project select

  2. 从 project select 命令的输出中，复制 cpk-... 开头的 runtime key。

  3. 将其填入 .env 文件中的 INTELLIGENCE_API_KEY 字段。

第 3 步：填写其他必需的环境变量

  • OPENAI_API_KEY：填入你的 OpenAI API 密钥。

  • 其他变量：.env.example 中的 INTELLIGENCE_API_URL、INTELLIGENCE_GATEWAY_WS_URL 等默认值通常无需修改（除非你自托管 Intelligence）。

  • KEY_ENCRYPTION_KEY：用于加密敏感数据。示例中的值是公开的，请务必为生产环境生成您自己的密钥：

    1
    openssl rand -base64 32

第 4 步：安装依赖并启动

1
2
bun install
bash scripts/start.sh

这个脚本会自动：

  • 启动 Docker 服务 (PostgreSQL, Bot 容器等)。
  • 运行数据库迁移。
  • 启动 API 服务器 (端口 3001)。
  • 启动 Web 应用 (端口 3010)。
  • 检查服务健康状态。

第 5 步：访问
在浏览器中打开 http://localhost:3010 即可开始使用。

🐳 部署为独立容器 (生产环境预览)

您可以将整个应用（包括 API、前端和内置 PostgreSQL）构建为一个独立的 Docker 镜像进行部署。

第 1 步：构建镜像

1
docker build -t openbot .

第 2 步：运行容器

1
2
docker run -p 3001:3001 --env-file .env \
  -e EMBEDDED_POSTGRES=on -v openbot-data:/var/lib/postgresql openbot
  • -e EMBEDDED_POSTGRES=on：启用容器内嵌的 PostgreSQL。
  • -v openbot-data:/var/lib/postgresql：持久化数据库数据。
  • 如果你想使用外部数据库，可以移除 EMBEDDED_POSTGRES 并设置 DATABASE_URL 环境变量指向你的数据库。

更详细的部署指南（包括 Kubernetes、副本数等）请参考项目中的 docs/deployment.md。

🔑 关键配置与首次设置

  • 单用户模式 (快速体验)：.env.example 中默认启用了 OPENBOT_SINGLE_USER=true，此时无需登录，所有请求都以管理员身份处理。这让你能立即开始体验。
  • 启用多用户和登录：要允许其他人访问，您需要删除 .env 中的 OPENBOT_SINGLE_USER 变量，并配置一个身份提供商（Google, Microsoft, Okta, SAML 或 OIDC）。同时必须设置 INITIAL_ADMIN_EMAILS 来指定初始管理员。
  • 存储凭证：Bot 使用的任何 API 密钥或登录凭证，都应通过 Web 界面的 /admin/credentials 页面存储，它们会被加密保存，且永远不会通过 API 返回。
  • 配置策略：您可以通过 /admin/boundaries 页面配置 CEL (通用表达式语言) 策略，精细控制 Bot 可以访问哪些网站、执行哪些命令或使用哪些工具。策略默认“拒绝一切”，您需要显式“允许”。

🧭 主要功能界面

启动后，您可以通过以下路径访问核心管理功能：

  • /：主页，浏览和开始对话频道。
  • /agents：创建、编辑和管理 AI 同事 (Bot)。
  • /channel/:id：与特定 Bot 对话，并实时观看其屏幕操作。
  • /admin/audit：查看所有操作的完整审计日志（允许、拒绝或失败）。
  • /admin/computers：查看、停止或重置 Bot 的独立电脑环境。
  • /admin/plugins：配置 MCP (模型上下文协议) 服务器，例如 Google Drive 或 Notion 连接器。

🛠️ 开发与构建命令

如果你打算修改代码，以下命令会很有帮助：

1
2
3
4
5
6
7
8
9
10
# 代码检查与测试
bun run format:check
bun run lint
bun run typecheck
bun run test
bun run build

# 修改数据库模式 (Schema) 后
bun run --filter server db:generate  # 生成迁移文件
bun run --filter server db:migrate   # 执行迁移

⚠️ 重要安全须知

  1. 本地运行：默认配置为在本地机器 (localhost) 上运行，请勿轻易暴露到公网。
  2. 网络隔离：agent-computer 服务绑定在 loopback 地址。请勿将其暴露给外部网络。
  3. 私有主机访问：.env 中的 AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS 选项仅适用于本地开发，在生产环境 (NODE_ENV=production) 下，如果设置了此选项，服务器将拒绝启动，以防止 Bot 访问内网服务。
  4. 加密密钥：确保 KEY_ENCRYPTION_KEY 是一个强随机密钥，并妥善保管。
  5. TLS：任何非 localhost 的部署都必须配置 TLS (HTTPS)，以保证登录 Cookie 等凭证的安全。

💎 总结

部署 OpenBot 的核心流程是：准备环境 → 克隆仓库 → 配置 .env (特别是 Intelligence Key 和 OpenAI Key) → 运行 bash scripts/start.sh。它会通过 Docker Compose 拉起所有依赖服务。项目设计为“模板”，意味着您应该在此基础上进行定制，添加自己的业务逻辑、策略和集成。