Paperclip 3周攒下3.5万星

大多数开发者在部署第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里。