基于Open Agents打造自己的云端智能体：完整指南-开发者社区

基于Open Agents打造自己的云端智能体：完整指南

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents

Open Agents是一个开源的云智能体（Cloud Agent）模板，帮助你快速构建属于自己的云端 AI 编程智能体：输入一段提示词，智能体就会在云端沙箱里自动读代码、改文件、跑命令，最后把代码改动提交成 Pull Request——全程无需打开笔记本电脑。它基于 Next.js + Vercel Sandbox 构建，自带 Web 界面、智能体运行时、沙箱编排和 GitHub 集成，开箱即用 🚀

Open Agents 是什么？

Open Agents 本质上是一个三层系统：

Web -> Agent workflow -> Sandbox VM

层级	职责	所在位置
Web 应用	认证、会话、聊天、流式界面	`apps/web/`
Agent 智能体	在 Vercel 上以持久化工作流方式运行	packages/agent/
Sandbox 沙箱	文件系统、Shell、Git、开发服务器、预览端口	packages/sandbox/

💡 核心设计：智能体 ≠ 沙箱

这是该项目最重要的架构决策：智能体不运行在虚拟机内部，而是在沙箱外部，通过文件读写、搜索、Shell 命令等工具与沙箱交互。

这个分离带来了几个直接好处：

✅ 智能体执行不再绑定单次请求的生命周期，可以跨多个持久化步骤运行
✅ 沙箱可以独立休眠（hibernate）和恢复（resume），节省资源
✅ 模型/提供商的选择与沙箱实现可以各自独立演进
✅ 虚拟机保持"纯粹的执行环境"，不会变成控制平面

想深入了解架构细节，推荐阅读 docs/agents/architecture.md

开箱即用的核心功能

Open Agents 提供了一整套完整的云智能体能力：

💬聊天驱动的编程智能体：内置文件、搜索、Shell、任务、技能（Skills）和网络抓取等工具
⚡持久化多步执行：基于 Workflow SDK 的运行、流式输出和随时取消
🔒隔离的 Vercel 沙箱：支持基于快照（snapshot）的恢复
🌿仓库克隆与分支工作：在沙箱内完成 Git 操作
📤自动提交、推送并创建 PR：任务成功后可自动完成（按偏好开启）
🔗会话分享：通过只读链接分享会话记录
🎙️语音输入：通过 ElevenLabs 转写（可选）

智能体可用的核心工具定义在 packages/agent/tools/index.ts，包括read、write、grep、glob、bash、task等；系统提示词由 packages/agent/system-prompt.ts 生成，确保智能体"端到端完成任务、不中途停止"。

本地快速启动：3 步跑起来

如果你想在本地先体验一下，只需要三步：

第 1 步：克隆仓库并安装依赖

git clone https://gitcode.com/GitHub_Trending/op/open-agents cd open-agents bun install

第 2 步：创建本地环境配置文件

cp apps/web/.env.example apps/web/.env

然后打开apps/web/.env填入必需的值。最小运行配置只需要两个变量：

POSTGRES_URL= BETTER_AUTH_SECRET=

其中BETTER_AUTH_SECRET可以用下面的命令生成：

openssl rand -base64 32

完整的环境变量清单可以在 apps/web/README.md 的说明和apps/web/.env.example中查阅。

第 3 步：启动应用

bun run web

打开浏览器访问http://localhost:3000，你的云端智能体就已经在本地跑起来了 ✨

部署到自己的云端：Vercel 部署步骤

想要一个真正"云端"的智能体？Open Agents 与 Vercel 深度集成，部署流程非常顺滑：

Fork 本仓库，并将其导入 Vercel（使用官方部署按钮时，Neon Postgres 会自动创建）
在 Vercel 项目设置中配置POSTGRES_URL和BETTER_AUTH_SECRET
部署一次，获得稳定的生产环境 URL
创建Vercel OAuth 应用（用于登录），回调地址填：https://YOUR_DOMAIN/api/auth/callback/vercel
填入NEXT_PUBLIC_VERCEL_APP_CLIENT_ID和VERCEL_APP_CLIENT_SECRET后重新部署
（可选）创建GitHub App以解锁完整的仓库访问、推送和 PR 能力：
- Homepage URL：https://YOUR_DOMAIN
- Callback URL：https://YOUR_DOMAIN/api/auth/callback/github
- Setup URL：https://YOUR_DOMAIN/api/github/app/callback

部署完成后，你的团队就可以各自拥有一个独立可定制的云端智能体平台，而不是使用别人的服务 🌐

沙箱如何工作：自动休眠与恢复

云端沙箱不是"一直开着"的——Open Agents 内置了智能的生命周期管理：

沙箱空闲30 分钟后自动休眠（先做快照，再停止虚拟机）
标准配置的硬超时为5 小时（Hobby 配置下为 40 分钟）
用户再次发消息或点击"Resume"时，沙箱从快照秒级恢复，之前的文件、开发服务器状态都还在

这意味着你可以放心把智能体交给它跑长任务，资源成本可控。整个状态机（provisioning → active → hibernated → 恢复）在 apps/web/SANDBOX-LIFECYCLE.md 中有完整说明。

项目结构速览：找到你想改的地方

Open Agents 是一个 Turborepo monorepo，目录职责清晰，非常适合 fork 后二次开发：

apps/web Next.js 应用：工作流、认证、聊天 UI packages/agent 智能体实现：工具、子智能体、技能、上下文管理 packages/sandbox 沙箱抽象与 Vercel 沙箱集成 packages/shared 共享工具

新手开发时建议重点关注这几个入口：

智能体本体：packages/agent/open-agent.ts
工具注册表：packages/agent/tools/index.ts
子智能体（explorer 只读探索 / executor 完整执行）：packages/agent/subagents/
数据库表结构：apps/web/lib/db/schema.ts
沙箱配置与超时：apps/web/lib/sandbox/config.ts

常用开发命令

日常开发和调试，这几个命令够用：

命令	作用
`bun run web`	启动开发服务器
`bun run check`	Lint + 格式检查
`bun run fix`	Lint + 格式自动修复
`bun run typecheck`	全部包类型检查
`bun run ci`	完整 CI：检查、类型检查、测试、迁移检查
`bun test`	运行所有测试