ufo-ai/ufo-core · 上手攻略

  • 仓库：ufo-ai/ufo-core
  • 链接：https://github.com/ufo-ai/ufo-core
  • 分类：AI 工程 / Agent 运行时
  • 作者：Jay
  • 更新：2026-10-02

这是什么

ufo-core 是一个开源的 AI Agent 运行时（runtime），让团队成员在聊天中给 AI Agent 分配任务，Agent 可以读取文件和执行命令来完成工作。它是 UFO 托管服务（ufo.ai）的开源实现，支持自托管，用自己的模型 API key 在自己的基础设施上运行 AI Agent。

核心设计哲学：一个进程，多种部署规模。SQLite + 本地文件即可跑单实例，PostgreSQL + S3 + Redis 可扩展到多实例集群。

解决什么问题

企业或个人运行 AI Agent 面临的实际问题：

  • Agent 执行边界不清晰：Agent 读取哪个目录？操作哪个用户权限？ufo-core 用 workspace 隔离 + 执行模式（local / remote）明确回答
  • Agent 身份与权限：Agent 不能借用说话者的身份——成员在聊天中 grant 一个 account 给 Agent，授权记录就是审计记录
  • Agent 持久化：每个 turn 是 DBOS workflow，崩溃可恢复，不丢状态
  • 多实例管理：从小笔记本到集群，一套代码，两种部署方式

快速安装

依赖

  • uv（Python 包管理器）
  • PostgreSQL（可选，SQLite 够用）
  • Docker（可选，使用 e2b sandbox 时）

安装步骤（本地模式，最简路径）

# 1. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 安装 ufo
git clone https://github.com/ufo-ai/ufo-core.git
cd ufo-core

# 3. 安装依赖
make install

# 4. 复制环境配置模板，填入三个模型 API key
cp .env.template .env
# 编辑 .env，填入 ANTHROPIC_API_KEY / OPENAI_API_KEY 等

# ⚠️ .env 拒绝裸 ANTHROPIC_API_KEY 和 OPENAI_API_KEY，
# 因为所有读取 .env 的工具都会获取所有值，建议用带前缀的变量名

# 5. 构建
make build

# 6. 初始化工作区和 admin 账号
make init EMAIL=your@email.com
# 输出：~/.ufoctl/token（CLI token）和 workspace 配置

# 7. 启动服务
make serve
# 监听 http://localhost:8710

# 8. 另一终端：连接客户端
mkdir -p ~/.ufo && install -m 600 ~/.ufoctl/token ~/.ufo/credentials
echo http://localhost:8710 > ~/.ufo/workspace
./client/target/debug/ufo "what can you do?"

托管模式（使用 ufo.ai 服务）

无需安装，自带模型 key：

# macOS / Linux 一键安装客户端
curl -fsSL https://ufo.ai/ufo | sh

# 运行并登录
ufo

# 首次登录用工作邮箱创建 workspace
# 访问 https://app.ufo.ai 或 Slack

托管服务支持 Slack 集成，团队成员无需安装 CLI，在 Slack 里直接给 Agent 分配任务。

核心用法

执行模式：local vs remote

# 默认：Agent 在你当前机器上操作（文件、命令以你的用户身份运行）
ufo "do something"

# Agent 在 workspace 的沙盒中操作
ufo --remote

# Agent 在配置的沙盒载体（Docker / e2b）中运行

⚠️ local 模式下 Agent 以当前用户身份读写当前目录；remote 模式下操作 workspace 配置的沙盒目录，隔离于用户目录。

边界 local remote
文件读取/编辑 用户当前目录 workspace 的 /workspace
命令执行 用户账号 配置的沙盒载体
执行边界 用户机器和账号 配置的沙盒载体
Agent 连接 turn 期间保持 turn 期间保持

持久化与恢复

Agent turn 中若客户端退出，turn 可继续；用 --wait SECONDS 提前退出，--resume <ID> 读取剩余结果。

每个 turn 是 DBOS workflow，崩溃可恢复，不丢中间状态。

浏览器工具（macOS）

macOS 上 Agent 可以用 browser tools 驱动 Chrome headless shell：

# 安装 chromium
npx playwright@$(uv run python -c 'from ufo.sdk.sandbox import PLAYWRIGHT_VERSION; print(PLAYWRIGHT_VERSION)') install chromium-headless-shell

# 启动时把 Chrome 路径加入 PATH
PATH="<dir>/chrome-headless-shell-mac-arm64:$PATH" make serve

⚠️ <dir> 是 Playwright 报告的路径（--dry-run 可打印）；Intel Mac 用 chrome-headless-shell-mac-x64。

调试工具

# 启动 debugger UI（需要 pnpm）
make debugger
# 然后 make serve

# 或 CLI 方式
uv run ufoctl debugger
# 在浏览器中打开 turns、steps、transcripts、memory

PostgreSQL 模式（多实例部署）

# 启动本地 PostgreSQL
make db
# 监听 127.0.0.1:5541，用户/密码/数据库均为 ufo

# 生成 PostgreSQL 配置
uv run python -c 'from ufo.cli import DEFAULT_CONFIG; print(DEFAULT_CONFIG, end="")' \
  | sed 's#sqlite+aiosqlite:///ufo.db#postgresql+asyncpg://ufo:ufo@127.0.0.1:5541/ufo#' > ufo.toml

扩展机制

ufo-core 是「一切皆扩展」架构：

# 扩展是一个 Python 包，声明一个入口点
[project.entry-points."ufo.extension"]
acme = "ufo_ext_acme.manifest:manifest"

扩展点覆盖：工具（tools）、连接器（connectors）、子 Agent（subagents）、表面层（surfaces）、模型提供商（model providers）、沙盒载体（sandbox carriers）。

管理扩展：

ufoctl ext search    # 搜索扩展
ufoctl ext install  # 安装
ufoctl ext remove   # 卸载

官方扩展和 packs 在 extensions/ 和 packs/ 目录，assistant 是默认 pack。

Bundle 打包：

ufoctl bundle
# 冻结部署镜像（镜像配方 + 客户端 + 固定配置 + lockfile）为一个制品
# 适合单节点、私有部署或集群扩展

典型适用场景

  1. 团队内部 AI 助手：成员在 Slack 或终端给 Agent 分配任务，Agent 读写工作目录内的文件
  2. 开发流程自动化：Code Review 生成、测试编写、文档更新等重复性开发任务
  3. 多租户隔离：每个 workspace 完全隔离，适合公司内部多个团队分别使用
  4. 个人 AI 工作站：笔记本上跑本地 Agent，处理文件、搜索、写代码
  5. 企业级 Agent 平台：PostgreSQL + S3 + Redis 集群，多实例并行处理任务

坑与注意

⚠️ local 模式安全边界：默认 local 沙盒（Seatbelt/Landlock）只限制写操作，能读取整个主机，内核不强制出口流量。处理不可信输入或多个 workspace 时，强烈建议切换到 Docker 或 e2b 沙盒。

⚠️ .env 变量命名：不能直接用 ANTHROPIC_API_KEY / OPENAI_API_KEY 裸名（会被所有读取 .env 的工具获取全部值），建议用带前缀的变量名并在 .env 中明确赋值。

⚠️ make init 需要邮箱：创建 admin 账号必须有真实邮箱，否则无法完成初始化。

⚠️ 浏览器工具只在 macOS 有文档：Linux/Windows 的 browser tools 路径配置文档不完整，README 只记录了 macOS 步骤。

⚠️ PostgreSQL + Redis 不是开箱即用：README 提供了配置路径但无 Docker Compose override 模板，高可用部署需要自行编写配置。

⚠️ 调试器需要 pnpm：make debugger 依赖 pnpm，提前安装。

与同类对比

方案 架构 执行模式 持久化 扩展方式
ufo-core 单进程 + workspace 隔离 local / remote / docker / e2b DBOS workflow（崩溃恢复） 纯 Python 扩展
Microsoft AutoGen 多 Agent 协作框架 Python 代码驱动 无内置 Python 装饰器
LangChain Agents 链式 Agent 框架 Python 运行时 无内置 LangChain 组件
OpenAI Agents SDK OpenAI 官方 Agent 框架 云端 + 本地 无内置 SDK 组件
CrewAI 多 Agent 协作平台 Python 运行时 无内置 YAML 配置

ufo-core 的核心差异：持久化 turn + workspace 隔离 + 聊天中授权，不是链式推理框架，而是真正的团队 Agent 运行时。

一句话推荐结论

ufo-core 是一个把 AI Agent 真正纳入团队工作流的运行时——聊天中授权、沙盒中执行、崩溃可恢复，适合需要多人共用 Agent、任务持久化、代码/文件操作边界清晰的企业或团队。个人用户可从托管版（ufo.ai）零配置起步，体验满意后再迁移到自托管。

⚠️ 存疑项：生产级高可用部署（PostgreSQL 多活 + Redis cluster）的参考配置尚未公开，官方文档以单实例为主；大规模团队使用前建议先在小规模验证稳定性。