一个 AI Agent 可以完成一次任务，但很难长期管理一组互相协作的 Agent：
谁负责决策，谁负责执行？
大任务如何拆分、分派和验收？
Agent 中断后，怎样接着上次的任务继续工作？
代码应该写到哪个目录？
为什么这次运行被触发？花了多少成本？
哪些操作必须由人批准？
Paperclip 就是这组问题的控制平面。它把多个 AI Agent 组织成一家公司，并提供组织架构、目标、项目、任务、运行记录、预算、审批和审计能力。
可以把它理解为：
Paperclip = AI Agent 的组织系统 + 任务系统 + 调度系统 + 治理系统。
Paperclip 本身不是大模型，也不是另一个聊天窗口。真正思考和执行的是 Codex、Claude Code、Gemini CLI 等运行时；Paperclip 决定“谁在什么上下文里，因为什么任务，在什么目录中执行，以及结果如何回写”。这也是官方文档对它的核心定位：What is Paperclip?。
| 单个 AI 助手 | Paperclip 管理的 Agent 团队 |
|---|---|
| 一段对话承担所有职责 | 每个 Agent 有明确角色和上级 |
| 上下文主要存在聊天记录中 | 目标、任务、评论和运行记录持久化 |
| 人工复制任务和结果 | 上级 Agent 可创建子任务并分派 |
| 失败后需要人工重新解释背景 | 下一次运行从任务和评论恢复上下文 |
| 通常只有模型调用记录 | 可查看任务树、Run、成本、审批和活动 |
| 权限与成本边界模糊 | 公司隔离、预算上限、审批门禁 |
因此，Paperclip 更适合“连续、可拆分、需要多角色协作”的工作，例如：
从需求分析到开发、测试和验收的软件项目；
内容选题、资料研究、撰写、审核和发布；
市场调研、竞品分析和定期经营报告；
需要人工审批的运营自动化流程。
它不适合替代即时问答。一个十分钟能完成的一次性问题，直接使用 ChatGPT、Codex 或 Claude 往往更简单。
flowchart TB
B["Human Board<br/>目标、审批、预算、验收"]
subgraph P["Paperclip Control Plane"]
O["Company / Org<br/>公司与汇报关系"]
G["Goals / Projects<br/>目标与项目"]
T["Tasks / Issues<br/>任务、子任务、评论"]
R["Heartbeat Runs<br/>唤醒、运行、日志"]
C["Governance<br/>预算、审批、审计"]
end
A["Adapter<br/>codex_local / claude_local / http"]
M["AI Runtime<br/>Codex CLI / Claude Code / 自定义服务"]
W["Workspace<br/>代码、文件、Git Worktree"]
B --> P
O --> T
G --> T
T --> R
C --> R
R --> A
A --> M
M --> W
M -->|"评论、状态、子任务、成本"| P
这套架构可以分成三层：
治理层：人类 Board 设置目标、预算和审批规则，并最终验收结果。
控制层：Paperclip 保存组织、项目和任务状态，触发运行并记录全过程。
执行层：Adapter 启动 Codex、Claude 等运行时，让它们在指定 Workspace 中完成工作。
关键边界是：
Paperclip 不替模型推理；
Adapter 不负责业务组织；
Agent 不能仅在聊天里“说完成了”，还要把任务状态和结果写回 Paperclip；
对文件类任务，Workspace 路径必须真实、可访问。
Adapter 的职责和扩展方式见官方的 Adapters Overview。
Company 是一个独立的 AI 组织。Agent、目标、项目、任务、预算和活动记录都属于某个 Company，跨公司默认隔离。
例如，我们创建一个名为 wxtech 的公司，其目标可以是：
通过可审计的 AI Agent 协作流程，交付小型 Web 产品和内部自动化工具。
Agent 是“角色配置 + 汇报关系 + AI 运行时 + 工作约束 + 预算”。
同一个 Codex 模型可以分别扮演 CEO、CTO 和工程师，但它们的职责、指令、任务权限和工作目录不同。
Paperclip 使用严格的组织层级：每个 Agent 只有一个直属上级，CEO 没有 Agent 上级，直接向人类 Board 汇报。详见 Key Concepts。
Goal 描述结果和方向，而不是具体动作。例如：
在一周内完成一个可离线运行、可演示、可验收的 Web 贪吃蛇游戏。
Goal 可以形成父子层级，并与 Project、Task 关联。
Project 把抽象目标连接到具体执行环境，包括任务集合、本地目录或远程仓库、环境变量、预算和 Workspace 策略。
可以用一句话区分：
Goal 回答“为什么做”；
Project 回答“在哪一组资源中推进”；
Task 回答“下一步具体做什么”。
Workspace 是 Agent 实际读取、修改和运行文件的目录。官方支持三种常见模式：
| 模式 | 含义 | 适用场景 |
|---|---|---|
| Project primary | 直接使用项目主目录 | 本地演示、单 Agent、低冲突任务 |
| Isolated | 为任务创建独立 Git worktree | 多 Agent 并行开发、需要隔离变更 |
| Reuse existing | 多个相关任务复用已有 Workspace | 同一功能链路、共享运行状态 |
本地首次演示建议使用 Project primary，先验证任务链和文件产出；多人或多 Agent 并发写代码时再启用 Isolated。详细机制见 Execution Workspaces。
UI 中通常称为 Task，API 和代码中称为 Issue，两者指同一个对象。Task 包含标题、描述、负责人、优先级、状态、项目、父任务和评论。
典型状态流转：
backlog → todo → in_progress → in_review → done
└────→ blocked
Agent 开工前需要 checkout。Checkout 是原子操作：同一个任务同时只能被一个 Agent/Run 占用，竞争者会收到 409 Conflict。任务生命周期和 API 示例见 Managing Tasks。
Agent 不是始终运行的进程。每次被唤醒后，会产生一个 Heartbeat Run：读取上下文、领取任务、调用模型、执行工具、回写进展，然后结束。
一个 Agent 可以由四类事件唤醒：
Task 被分配给它，或开放任务收到新评论；
人工点击 Wake now / Run Heartbeat；
定时 Heartbeat 到点；
Routine 按计划或 Webhook 创建任务。
多数 Agent 推荐：
Heartbeat on interval = Off
Wake on demand = On
也就是说，有任务再运行，不要每几分钟无事空转。官方也把事件驱动作为默认建议：Heartbeats & Routines。
以“给 CEO 下发一个开发任务”为例：
sequenceDiagram
participant H as Human Board
participant P as Paperclip
participant C as CEO Agent
participant T as CTO Agent
participant F as Full-stack Agent
participant W as Workspace
H->>P: 创建任务并分配给 CEO
P->>C: 任务分配触发 Run
C->>P: checkout 父任务
C->>P: 创建并分配 CTO 子任务
P->>T: 唤醒 CTO
T->>P: checkout 技术方案任务
T->>P: 创建并分配开发子任务
P->>F: 唤醒全栈工程师
F->>W: 编写代码、运行检查
F->>P: 评论结果并更新为 done
T->>P: 复核产物并汇总
C->>P: 对父任务给出最终交付说明
P-->>H: 展示任务树、日志和结果
对一次 Run 来说，内部过程可以概括为：
Paperclip 根据任务分配、评论、Routine 或人工操作创建 Run。
Paperclip 确定 Agent 身份、触发原因、目标任务和 Workspace。
Adapter 启动对应的 AI Runtime，并注入当前 Run 的环境和上下文。
Agent 查询自己的任务，原子 checkout 后开始工作。
Agent 可以修改文件，也可以通过 Paperclip API 创建子任务、评论和更新状态。
Paperclip 保存 transcript、结构化事件、任务变更和成本。
Run 结束；未完成工作由下一次唤醒继续，而不是依赖一个永不结束的会话。
官方本地安装要求 Node.js 20 或更高版本，并使用普通用户执行：
node --version
npm install -g corepack
corepack enable
corepack prepare pnpm@latest --activate
npx paperclipai onboard --yes
首次命令会创建 ~/.paperclip/ 配置、初始化内嵌数据库，并默认启动：
http://localhost:3100
以后重新启动：
npx paperclipai run
不要用 sudo 启动本地内嵌 PostgreSQL。完整说明见 Installation。
在 Paperclip 仓库中：
pnpm install
pnpm dev
默认不设置 DATABASE_URL 时使用内嵌 PGlite/PostgreSQL。启动后可先验证：
curl http://localhost:3100/api/health
curl http://localhost:3100/api/companies
| 凭据 | 用途 | 谁提供 |
|---|---|---|
| OpenAI / Anthropic API Key | 调用模型服务 | 模型服务商 |
PAPERCLIP_API_KEY |
Agent 调用 Paperclip API，查询和更新任务 | Paperclip |
本地 Adapter 运行时，Paperclip 可以为当前 Run 注入短期 Agent JWT；因此通常不应该把固定的 PAPERCLIP_API_KEY 手写进 Agent 指令或提交到仓库。长期 Agent API Key 主要用于外部脚本或远程 Agent 接入。
Agent 调用 API 时的请求形式为：
curl http://localhost:3100/api/agents/me \
-H "Authorization: Bearer $PAPERCLIP_API_KEY" \
-H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID"
Board、Agent API Key 和本地 Run JWT 的区别见 Authentication。
下面是一条适合现场分享的最小完整链路。它同时验证组织委派、任务树、Workspace 和文件交付。
mkdir -p /Users/w/ai/paperclip-project
cd /Users/w/ai/paperclip-project
git init
在 Paperclip 中创建 Project：
| 配置项 | 示例值 |
|---|---|
| Name | Web 贪吃蛇演示 |
| Description | 验证 CEO → CTO → 全栈工程师的任务委派和交付链路 |
| Local folder / cwd | /Users/w/ai/paperclip-project |
| Default workspace mode | Project primary |
如果使用 Isolated 模式，需要正确配置 Git base ref 和 worktree 目录；第一次演示不要同时引入这些变量。
Human Board
└── CEO
└── CTO
└── 全栈工程师
三个角色都可以使用 codex_local，也可以让不同角色使用不同 Adapter。例如 CEO/CTO 使用 Codex，工程师使用 Claude Code。Paperclip 管的是任务和汇报关系，不要求所有 Agent 使用同一种模型。
本地示例配置：
| 角色 | 核心职责 | Adapter / 模型示例 |
|---|---|---|
| CEO | 理解业务目标、拆出 CTO 子任务、最终汇总 | codex_local / gpt-5.4 |
| CTO | 给出技术方案、验收标准、拆出开发子任务 | codex_local / gpt-5.4 |
| 全栈工程师 | 修改 Workspace 文件、测试、回报结果 | codex_local / gpt-5.4 |
gpt-5.4是本地演示选择，不代表 Paperclip 的官方默认模型。模型名必须与当前 CLI 和账户实际支持的名称一致。
如果 Codex CLI 需要通过本机 7890 代理访问外网，项目或 Agent 环境中至少保证本地地址不经过代理：
HTTP_PROXY=http://127.0.0.1:7890
HTTPS_PROXY=http://127.0.0.1:7890
NO_PROXY=localhost,127.0.0.1,::1
否则模型请求可能正常，但 Agent 回写 localhost:3100 时被代理拦截，表现为不断检查网络或 API。
CEO 指令的关键部分：
你是公司的 CEO，负责理解目标、拆分工作和验收结果。
收到软件开发任务时：
1. 先 checkout 当前任务并确认目标与验收标准；
2. 不要自己编写代码，也不要反复诊断 Paperclip 网络；
3. 创建一个关联当前 Project 的子任务，分配给 CTO；
4. 子任务必须保留 parentId，并写清交付物和验收标准；
5. 等待 CTO 汇报后，在父任务中向 Board 汇总。
CTO 指令的关键部分：
你是 CTO，负责技术方案、任务拆分和技术验收。
收到 CEO 子任务时：
1. 给出简洁的技术方案和文件结构；
2. 创建开发子任务并分配给全栈工程师；
3. 子任务继承当前 Project、Goal 和父任务 Workspace；
4. 工程师完成后检查文件与测试结果，再向 CEO 汇报。
全栈工程师指令的关键部分：
你是全栈工程师，只处理分配给自己的开发任务。
1. checkout 后在 PAPERCLIP_WORKSPACE_CWD 指向的目录工作；
2. 先读取任务和父任务上下文，再修改文件；
3. 必须实际运行可用的检查或测试；
4. 在任务评论中写明修改文件、验证命令和结果；
5. 完成后把任务更新为 done；无法推进时更新为 blocked 并说明原因。
把下面内容作为一个新 Task，关联 Web 贪吃蛇演示 Project，并分配给 CEO：
标题：交付一个可演示的 Web 贪吃蛇游戏
目标：
在当前 Project Workspace 中交付一个无需构建、浏览器直接打开即可运行的贪吃蛇游戏。
组织要求：
- CEO 负责理解目标，并创建、分配 CTO 技术方案子任务；
- CTO 负责确定技术方案和验收标准，并创建、分配全栈开发子任务；
- 全栈工程师负责实际编码和测试；
- 所有角色都在自己的任务评论中汇报，不越级代替下属完成。
功能验收：
1. 方向键和 WASD 均可控制；
2. 显示当前分数和本地最高分；
3. 支持暂停、继续和重新开始；
4. 支持慢、中、快三档速度；
5. 撞墙或撞到自身时结束，并显示结果；
6. 页面在常见桌面浏览器中布局完整；
7. 不依赖外部 CDN 或后端服务。
交付物：
- index.html
- style.css
- game.js
- README.md，包含启动方式和人工验收步骤
完成定义：
- 文件真实写入 Project Workspace；
- 至少执行一次语法或启动检查；
- 全栈工程师完成开发，CTO 完成技术复核，CEO 最终向 Board 汇总。
任务创建后无需打开定时 Heartbeat。保持三个 Agent 为 Active、Wake on demand = On，Task 分配会触发 CEO，CEO 创建并分配子任务又会触发 CTO，依次向下执行。
演示时不要只看聊天内容，应按以下顺序验证：
Org：CEO、CTO、全栈工程师的汇报关系正确。
Related work：根任务下面出现 CTO 子任务和全栈开发子任务。
Activity / Runs：每次分配都产生对应 Agent Run，且没有长时间停在 Running。
Chat：评论包含方案、进度、验证命令和交付总结。
Workspace：/Users/w/ai/paperclip-project 中真实出现四个交付文件。
Status：子任务先完成，再由 CTO、CEO 逐层汇总父任务。
可在终端做最终检查：
cd /Users/w/ai/paperclip-project
find . -maxdepth 1 -type f -print
# 打开
open index.html
这类问题通常不是模型不够聪明，而是控制面上下文或角色指令不完整。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 一直分析网络、Token、数据库 | Agent 无法调用 Paperclip API，或不知道应通过 API 建子任务 | 检查 Run 环境中的 API URL/Token；测试 /api/agents/me |
| CEO 自己开始写代码 | CEO 指令没有禁止亲自实现，或没有可用下属 | 明确“创建 CTO 子任务，不直接编码”；检查 Org |
| 评论发出但没有新 Run | Agent 非 Active、Wake on demand 关闭或处于 error | 恢复 Agent，检查 Runs 中的错误 |
| 提示 Company is not active | Company 被暂停或未激活 | 在 Company 设置中恢复为 Active |
| 提示 blocked，评论后仍不执行 | 评论不会自动改变任务状态 | 解决阻塞后将任务移回 todo |
| 状态是 in_progress，但无动作 | 上一次 checkout/run 中断，任务仍被旧 Run 占用 | 查看最新 Run，停止异常 Run，必要时重新排队任务 |
| Agent 在错误目录创建文件 | Project 未绑定路径，或 Run 没拿到 Workspace | 检查 Project primary workspace 和 PAPERCLIP_WORKSPACE_CWD |
| 绑定 Project 后旧任务仍用旧目录 | 已存在 Run 的上下文不会自动重建 | 停止旧 Run，重新分配或创建新 Task |
| 使用代理后本地 API 不通 | localhost:3100 也被送入代理 |
设置 NO_PROXY=localhost,127.0.0.1,::1 |
| 模型启动即失败 | CLI 未登录、模型名无权限或命令不可见 | 先在同一系统用户下独立执行 CLI，并查看 Run transcript |
建议使用固定诊断顺序：
Company Active?
↓
Agent Active + Wake on demand?
↓
Task 是 todo 且分配正确?
↓
最新 Run 是否启动，transcript 报什么错?
↓
/api/agents/me 是否成功?
↓
Project / Workspace 路径是否正确?
↓
AI CLI 本身是否能在同一用户、同一目录运行?
不要让 CEO 在任务里反复“修 Paperclip”。控制平面或环境故障应由人类管理员在 Run 外修复；CEO 的职责是拆分和协调业务任务。
推荐从三层以内开始：
Board → 负责人 Agent → 执行 Agent
层级越深，任务拆分、等待、成本和错误恢复越复杂。只有当一个职责长期稳定、任务量足够大时，才值得增加专职 Agent。
高质量任务至少包含：
目标：为什么做；
范围：做什么、不做什么；
交付物：文件、文档、数据或链接；
验收标准：如何判断完成；
验证方式：命令、测试或人工检查；
升级规则：什么情况必须询问人类。
角色分工不能代替任务验收。Agent 是否可靠，很大程度取决于“完成”的定义是否可验证。
日报、周报、巡检等周期任务应创建 Routine，而不是给所有 Agent 开启高频 Heartbeat。Routine 到点后创建或重开 Task，再通过分配唤醒 Agent，触发原因和结果都可追踪。
当多个 Agent 同时修改同一个仓库时，使用 Isolated Workspace：每个任务获得独立 Git worktree 和分支，完成后再人工审查、测试和合并。不要让多个写入型 Agent 并发操作同一个 Project primary 目录。
创建后续子任务时，应设置 parentId，或显式使用 inheritExecutionWorkspaceFromIssueId，否则子任务可能无法继承父任务的执行目录。
建议必须人工批准的动作包括：
招聘新 Agent 或改变组织结构；
大幅提高预算；
发布生产版本；
删除数据或不可逆迁移；
对外发送消息、付款或签署承诺。
Paperclip 的 Approval 层可以关联任务，审批结果会再次唤醒请求 Agent。API 机制见 Approvals。
公司和 Agent 都应设置月度预算。预算的价值不只是统计费用，而是在循环、误配置或异常任务持续调用模型时自动停止消耗。
生产环境还应做到：
模型 Key 和服务凭据进入 Secret Store，不写入任务和仓库；
Agent 只获得完成职责所需的工具与目录权限；
对外部署使用 authenticated 模式、HTTPS 和明确的公开地址；
定期查看失败 Run、异常高成本和长期 blocked 的任务。
不要用“Agent 回复了一段看起来不错的话”作为成功标准。至少检查五件事：
| 维度 | 成功标准 |
|---|---|
| 组织 | 工作确实按 CEO → CTO → 工程师委派，而不是一个 Agent 包办 |
| 状态 | Task 被 checkout、持续更新并最终进入正确状态 |
| 产物 | 文件或业务结果真实存在，而不是只在评论中描述 |
| 验证 | 有可复现的测试命令、结果或人工验收步骤 |
| 治理 | Run、评论、成本、审批和异常都能追溯 |
真正的价值不是“零人”，而是把 AI 的执行从一次性对话升级成：
有组织、有任务、有环境、有边界、有记录、可恢复的持续工作。
如果您喜欢我的文章，请点击下面按钮随意打赏，您的支持是我最大的动力。
最新评论