需要把多个 AI Agent 编排成有组织架构、目标…

适用于用 Paperclip 开源编排平台搭建和运行多 Agent 公司，从安装、建模、API 集成到心跳调度、预算治理和排障。

适用场景

解决思路

1. 运行 `npx paperclipai onboard --yes` 完成快速上手：它会克隆仓库、安装依赖、初始化内置 PostgreSQL 并启动服务器。
2. 手动搭建时依次执行 `git clone https://github.com/paperclipai/paperclip.git`、`cd paperclip`、`pnpm install`、`pnpm dev`；确保 Node.js 20+ 和 pnpm 9.15+，API 服务默认位于 `http://localhost:3100`，本地开发自动创建内置 PostgreSQL。
3. 生产环境通过环境变量指向外部 Postgres 和对象存储：在 `.env` 设置 `DATABASE_URL`、`STORAGE_BUCKET`、`STORAGE_REGION`、`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、`PORT=3100`。
4. 使用 CLI 管理生命周期：`pnpm dev` 启动开发模式 API+UI，`pnpm build` 构建生产，`pnpm start` 启动生产，`pnpm db:migrate` 执行迁移，`pnpm db:seed` 灌入演示数据，`pnpm test` 跑测试，`npx paperclipai onboard --yes` 自动全套初始化。
5. 按核心对象建模：用 Company 作为顶层命名空间，Agent 作为 AI 员工，Goal 作为层级业务目标，Task/Ticket 作为工作单元，Heartbeat 作为 cron 唤醒，Org Chart 作为汇报关系，Budget 作为月度 token/成本上限，Governance 作为审批门禁。
6. 所有 REST 请求发到 `http://localhost:3100/api/v1`，并带请求头 `Authorization: Bearer ${process.env.PAPERCLIP_API_KEY}` 和 `Content-Type: application/json`。
7. 创建公司：向 `POST /companies` 发送 `{ name, mission, slug }`，从响应取得 `company.id`（如 `cmp_abc123`）。
8. 注册 Agent：向 `POST /companies/${companyId}/agents` 发送 `{ name, role, runtime, endpoint, budget: { monthly_usd }, heartbeat: { cron, enabled }, reports_to }`；`runtime` 可选 `openclaw`、`claude-code`、`codex`、`cursor`、`bash`、`http`。
9. 创建目标：向 `POST /companies/${companyId}/goals` 发送 `{ title, description, parent_goal_id, owner_agent_id, due_date }`；`parent_goal_id: null` 表示顶层目标。
10. 创建任务：向 `POST /companies/${companyId}/tasks` 发送 `{ title, description, assigned_to, goal_id, priority }`，用 `goal_id` 把任务挂到目标谱系。
11. 查询某 Agent 的任务：GET `/agents/${agentId}/tasks?status=open`。
12. 向任务会话发消息：POST `/tasks/${taskId}/messages`，发送 `{ role, content, tool_calls: [{ tool, input, output }] }`。
13. 上报 Agent 成本：POST `/agents/${agentId}/cost`，发送 `{ tokens_in, tokens_out, model, task_id }`；Paperclip 会原子性执行预算限制，预算耗尽即停止 Agent。
14. 发送心跳：POST `/agents/${agentId}/heartbeat`，响应包含 `instructions`（当前组织关注点）和 `tasks`（分配给该 Agent 的开放任务）。
15. 封装 TypeScript SDK：创建 `lib/paperclip-client.ts`，实现 `PaperclipClient` 类，构造函数读取 `PAPERCLIP_BASE_URL` 和 `PAPERCLIP_API_KEY`，内部 `req<T>` 统一发请求并在非 2xx 时抛错。
16. 在 SDK/Client 中实现 `heartbeat(agentId)` 调 POST `/agents/${agentId}/heartbeat`，`completeTask(taskId, summary)` 用 PATCH `/tasks/${taskId}` 发送 `{ status: 'done', completion_summary }`，`reportCost(agentId, payload)` 调 POST `/agents/${agentId}/cost`。
17. 实现最小 Agent 循环：读取 `PAPERCLIP_AGENT_ID`，在 `runHeartbeat()` 中先发心跳，遍历 `tasks`，执行你的 `doWork(task, instructions)`，成功后 `completeTask` 并 `reportCost`，失败则记录错误并交给 Paperclip 按治理规则重新分配或升级。
18. 心跳可由 Paperclip 的 cron 驱动，也可在 Agent 内用 `setInterval(runHeartbeat, 60_000)` 自轮询并立即先跑一次 `runHeartbeat()`。
19. 注册任意语言的 HTTP Agent：让 Paperclip 向你的 `POST /work` 发送 `{ agent_id, task: { id, title, description, goal_ancestry }, instructions, context }`，你返回 `{ status: 'done' | 'blocked' | 'delegated', summary, tokens_in?, tokens_out?, model?, delegate_to? }`。
20. 多公司隔离：在同一部署中用 `createCompany` 创建多个 Company，各自拥有独立 agents、goals、tasks、budgets 和 audit log，互不泄露数据。
21. 治理审批：GET `/companies/${companyId}/approvals?status=pending` 获取待审批项；PATCH `/approvals/${approvalId}` 发送 `{ decision: 'approved', note }` 批准招聘等事项。
22. 回滚配置：POST `/agents/${agentId}/config/rollback` 发送 `{ revision: 3 }`。
23. 配置环境变量：必填 `PAPERCLIP_API_KEY`；数据库用 `DATABASE_URL`；存储用 `STORAGE_DRIVER=local|s3`、`STORAGE_BUCKET`、`STORAGE_REGION`、`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`；服务器用 `PORT=3100`、`BASE_URL`；Agent 侧用 `PAPERCLIP_BASE_URL`、`PAPERCLIP_AGENT_ID`。
24. 经理 Agent 委派模式：在经理的 heartbeat 处理器中遍历 `tasks`，若 `task.complexity === 'high'`，则 POST `/tasks/${taskId}/delegate` 发送 `{ to_agent_id: engineerAgentId }` 沿组织架构向下委派。
25. @-mention 触发模式：POST `/tasks/${taskId}/messages`，发送 `{ role: 'human', content: '@${designerAgentId} ...' }`；Paperclip 会把 mention 作为触发器送到被 @ Agent 的下一次 heartbeat。
26. 导出公司模板：GET `/companies/${companyId}/export`，把响应 blob 写入 `.paperclip` 文件；导出包会清理 secrets。
27. 导入公司模板：用 `FormData` 追加 `file` 指向 `.paperclip` 文件，POST `/companies/import`，并带 `Authorization: Bearer ${process.env.PAPERCLIP_API_KEY}`。
28. 排障 `ECONNREFUSED localhost:3100`：先运行 `pnpm dev` 启动服务器。
29. 排障 `401 Unauthorized`：检查 `PAPERCLIP_API_KEY` 已设置且与服务端配置一致。
30. 排障 Agent 不唤醒：确认 `heartbeat.enabled: true`、cron 表达式有效，并检查服务端调度器日志。
31. 排障预算立即耗尽：调高 `monthly_usd`，或检查 `POST /agents/:id/cost` 的 `tokens_in`/`tokens_out` 是否超报。
32. 排障任务卡在 `open`：Agent 可能离线或 heartbeat 配错，检查 `/api/v1/agents/:id/status`。
33. 排障数据库迁移错误：拉取新提交后运行 `pnpm db:migrate`。
34. 排障内置 PostgreSQL 启动失败：5433 端口可能被占用，在 `.env` 设置 `EMBEDDED_PG_PORT=5434`。
35. 排障组织架构不解析：先创建上级 Agent 并确保 `reports_to` 的 agent ID 已存在，按自上而下顺序创建。
36. 参考资源：文档 https://paperclip.ing/docs，GitHub https://github.com/paperclipai/paperclip，Discord https://discord.gg/m4HZY7xNG3，Clipmart 公司模板 https://paperclip.ing/clipmart（coming soon）。

适用边界 · 注意事项

• 不使用 Paperclip 或无法访问其服务/API/SDK 时，不能用这套做法。
• 只需要单 Agent、单次脚本或简单自动化，不需要公司级组织、目标、预算和治理时，Paperclip 会过度复杂。
• 生产部署缺少 Node.js 20+、pnpm 9.15+、PostgreSQL/S3 等基础设施时，不适合直接照搬生产配置。