大多数开发者在部署第5个AI代理时都会撞上同一堵墙。Claude Code在终端窗口里重写后端服务，Codex在另一个窗口生成测试用例，Cursor正在改组件，还有三个标签页你早就忘了检查。没人知道别人在干什么，成本蹭蹭涨，两个代理重复干同一块活儿，某个代理跑了6小时一无所获——因为根本没人给它定过清晰目标。
Paperclip就是来修这个的。这是一个开源协调平台，把你手里散落的AI代理整编成一家"正规公司"：组织架构图、明确分工、任务管理、预算上限、审计日志，该有的都有。GitHub上35,000+星，用时不到三周。这个数字本身就在说话——多少开发者被同样的 frustration（挫败感）折磨过。
这篇文章讲清楚怎么搭起来、怎么搭你的第一家"代理公司"、怎么让它真的跑起来，而不是让你盯着六个终端窗口当监工。
它到底是什么：不是造轮子，是当管家
装之前得先明白Paperclip的定位。它不是代理本身，不替代你的AI供应商，也不给你加个聊天界面。它是代理的协调层——组织它们、跟踪进度、控制预算、同步公司级目标上下文。
支持清单：Claude Code、OpenAI Codex、Cursor、Gemini CLI，以及任何支持webhook或heartbeat的代理。你自己把代理接进来，Paperclip负责管公司。
如果你只是偶尔用一个代理，别折腾这个。如果你同时在跑多个代理，它是基础设施级别的工具。
环境要求极简：Node.js 20+、pnpm 9.15+。不用外接数据库，内置PostgreSQL。
一行命令起步：
npx paperclipai onboard --yes
这条命令拉下CLI、跑完默认配置、在3100端口启动服务。浏览器开 http://127.0.0.1:3100 进控制台。
想改代码或贡献：
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Docker路线：
docker compose -f docker-compose.quickstart.yml up --build
本地文件结构长这样：
~/.paperclip/instances/default/
config.json — 服务器和存储配置
db/ — PostgreSQL数据文件
secrets/master.key — 加密密钥
logs/ — 服务器日志
data/storage/ — 文件附件
workspaces// — 每个代理的工作目录
本地模式用 local_trusted 认证，不用注册账号直接进控制台。
自检命令：
paperclipai doctor
自动修复：
paperclipai doctor --repair
搭你的第一家"公司"
"公司"是代理、任务、目标、预算的顶层容器。创建命令：
npx paperclipai company create --name "MySoftwareCo"
控制台里能看到公司仪表板，侧边栏有：代理(Agents)、任务(Tasks)、目标(Objectives)、预算(Budgets)、审计(Audit)。
先定目标。目标描述公司要达成什么，代理据此对齐上下文。创建命令：
npx paperclipai objective create \
--company "MySoftwareCo" \
--name "Ship v2 API" \
--description "Rewrite the user service with proper auth and rate limiting"
目标会进系统提示词，每个代理都知道公司在忙什么。
然后设预算。预算是硬性上限，防止代理烧钱失控。创建命令：
npx paperclipai budget create \
--company "MySoftwareCo" \
--name "Monthly API Dev" \
--limit 500.00 \
--currency USD
预算可以按公司、项目或单个代理切分。触及上限时代理自动暂停，等人工批复。
把代理接进组织
代理是干活的员工。Paperclip不内置代理，你得把现成的接进来。
Claude Code的接入方式：
终端里启动Claude Code时加环境变量：
export PAPERCLIP_WEBHOOK_URL="http://127.0.0.1:3100/webhook"
export PAPERCLIP_AGENT_ID="claude-backend"
export PAPERCLIP_COMPANY="MySoftwareCo"
claude
Claude Code的每次操作都会同步到Paperclip：执行了什么命令、改了哪些文件、花了多长时间。
Cursor的接入方式：
Cursor不支持直接webhook，用heartbeat模式。启动一个轻量适配器：
npx paperclipai adapter cursor \
--company "MySoftwareCo" \
--agent-id "cursor-frontend" \
--workspace "./frontend"
适配器每30秒扫描一次Cursor的工作区，把文件变更、终端输出、耗时推给Paperclip。
OpenAI Codex的接入方式：
Codex CLI原生支持webhook：
codex --webhook http://127.0.0.1:3100/webhook \
--agent-id "codex-tests" \
--company "MySoftwareCo"
通用webhook格式：
POST /webhook
Content-Type: application/json
"agent_id": "string",
"company": "string",
"event": "task_start|task_complete|file_change|command_run|error",
"data": { ... },
"timestamp": "ISO8601",
"cost": { "input_tokens": n, "output_tokens": n, "usd": n.nnn }
任何能发这个JSON的代理都能接进来。
任务系统：别让代理各自为战
没有任务管理，多代理就是 chaos（混乱）。Paperclip的任务系统确保代理知道该干什么、什么时候干、跟谁协作。
创建任务：
npx paperclipai task create \
--company "MySoftwareCo" \
--name "Implement OAuth flow" \
--description "Add Google and GitHub OAuth to the auth service" \
--objective "Ship v2 API" \
--budget "Monthly API Dev" \
--assignee "claude-backend" \
--priority high \
--deadline "2024-01-15T23:59:59Z"
任务进了系统，Claude Code的上下文里会自动出现这个任务描述。它知道优先级、截止日期、花的是哪个预算。
任务状态流转：backlog（待办）→ in_progress（进行中）→ review（审核）→ done（完成）→ archived（归档）。
代理完成任务时推送：
"event": "task_complete",
"data": {
"task_id": "task_123",
"summary": "Implemented OAuth with Passport.js, added tests",
"files_changed": ["auth/oauth.js", "tests/oauth.test.js"],
"cost": { "usd": 12.34 }
控制台里能看到完整时间线，谁干了什么、花了多少、产出是什么。
依赖关系：任务可以互相依赖。A任务完成前B任务不能启动。Paperclip会自动协调代理的执行顺序。
npx paperclipai task link --from task_123 --to task_456 --type blocks
组织架构图：看得见谁在干什么
代理多了之后，"谁负责什么"会变成谜。Paperclip的组织架构图功能把这个问题可视化。
控制台里打开 Org Chart（组织架构图）标签页，能看到：
• 每个代理的当前状态：空闲/工作中/阻塞/错误
• 正在执行的任务
• 实时成本累计
• 最近活动的时间线
代理按团队分组。你可以创建"后端组"、"前端组"、"测试组"，把代理放进去。
npx paperclipai team create \
--company "MySoftwareCo" \
--name "Backend Squad" \
--lead "claude-backend"
npx paperclipai team join \
--team "Backend Squad" \
--agent "codex-tests"
团队有共享的上下文窗口。组内代理能看到彼此的任务状态，减少重复劳动。
实时同步用WebSocket。代理状态变化时，组织架构图自动刷新，不用手动刷新页面。
审计与复盘：钱花哪了、时间去哪了
多代理最大的坑是"不知道钱怎么没的"。Paperclip的审计日志给每个操作留痕。
查询命令：
npx paperclipai audit list \
--company "MySoftwareCo" \
--from "2024-01-01" \
--to "2024-01-31"
输出包括：
• 每次API调用的token数和费用
• 执行的命令和返回码
• 文件变更的diff摘要
• 任务切换的时间点
成本分析：
npx paperclipai budget report \
--company "MySoftwareCo" \
--budget "Monthly API Dev"
报告按代理、按任务、按日期维度拆解。你能看到"cursor-frontend花了$200改CSS"这种细节。
异常检测：系统会自动标记异常模式。比如某个代理连续3小时没有文件输出，或者单次调用花费超过预算的10%。
导出功能：审计日志可以导出为JSON或CSV，进你自己的BI工具。
高级玩法：把Paperclip嵌进你的工作流
基础跑通之后，可以玩更细的。
CI/CD集成：在GitHub Actions里启动Paperclip，让代理在PR上自动跑。
workflow片段：
- name: Start Paperclip
run: |
npx paperclipai onboard --yes
npx paperclipai company create --name "PR-Review-$(echo ${{ github.sha }} | cut -c1-7)"
npx paperclipai agent register --name "pr-reviewer" --type claude
npx paperclipai task create --name "Review PR" --assignee "pr-reviewer"
- name: Run Review
env:
PAPERCLIP_WEBHOOK_URL: "http://127.0.0.1:3100/webhook"
run: claude --prompt "Review this PR: ${{ github.event.pull_request.html_url }}"
每次PR自动生成一个临时公司，跑完销毁，成本完全隔离。
自定义适配器：如果你的代理不走标准webhook，可以写适配器。Paperclip提供Node.js SDK：
import { PaperclipClient } from '@paperclipai/sdk'
const client = new PaperclipClient({
baseUrl: 'http://127.0.0.1:3100',
company: 'MySoftwareCo'
await client.agent.heartbeat({
agentId: 'my-custom-agent',
status: 'working',
currentTask: 'task_789',
cost: { usd: 0.05 }
插件系统：控制台可以插自定义面板。写一个React组件，打包成umd格式，放进 ~/.paperclip/plugins/，重启后出现在侧边栏。
多公司管理：如果你同时管多个项目，Paperclip支持公司切换。
npx paperclipai company list
npx paperclipai company switch --name "OtherProject"
配置隔离，数据隔离，预算隔离。
踩坑记录：来自早期用户的反馈
GitHub Issues里能看到真实用户的声音。
「heartbeat间隔设太短，日志把磁盘撑爆了。」—— 默认30秒，有人改成5秒，一天写了50GB日志。现在文档里加了警告。
「PostgreSQL在WSL2上性能崩了。」—— Windows用户常见问题，官方推荐用Docker Desktop的WSL2后端，或者直接用Docker Compose。
「代理崩溃后状态卡在'in_progress'，阻塞了依赖任务。」—— 加了超时检测，代理30分钟没心跳自动标记为stalled。
「预算警告阈值不能自定义。」—— v0.3.0加了 --threshold 参数，默认80%警告，可改。
「想要Slack通知。」—— 社区插件已经有了，webhook推给Slack Incoming Webhook。
版本节奏：每周发minor版本，breaking change进major。v1.0之前API可能变，锁版本建议用 exact version。
路线图公开：GitHub Projects里能看到。Q1重点是多租户支持（团队版），Q2是云端托管选项。
它不能做什么：边界意识
讲清楚限制，避免期待错位。
Paperclip不执行代码。它只协调代理，代码执行在代理自己的环境里。如果代理在沙箱里跑，Paperclip管不了沙箱内部。
不解决代理能力问题。如果Claude Code看不懂你的代码库，Paperclip帮不了。它只是让多个"看不懂的代理"不要互相干扰。
不替代版本控制。代理改的文件还是要进git。Paperclip跟踪文件变更，但真正的版本管理靠Git。
不做自动故障恢复。代理崩了它会标记状态，但不会自动重启。你得自己配supervisor或者systemd。
不保证安全。本地模式的 local_trusted 认证假设你信任本机用户。多用户场景要配OIDC或LDAP，文档里有指引但不算一键开箱。
成本跟踪是尽力而为。代理报的cost依赖供应商API返回，有些调用（比如本地模型）可能没有费用数据，会显示为$0。
一个用户在公司仪表板的截图里评论：「终于能看到钱去哪了，之前每个月AI账单像黑箱。」这条反馈被团队置顶在README里。
热门跟贴