Paperclip 是什么？一篇讲清“AI 公司操作系统”与 TaoToken 的接入方式

1. Paperclip 是什么：把一群 AI Agent 管成一家公司的开源编排系统

Paperclip 是一个开源的 AI Agent 编排平台，官方定位是 "Open-source orchestration for zero-human companies"，翻译过来就是面向"零人公司"的开源编排系统。它能做什么？简单说，它不生产 AI 能力，它管理 AI 能力。适合谁？手里同时跑着 Claude Code、Codex、Cursor、Trae 等多个 Agent，已经开始被"谁在干什么、花了多少钱、任务有没有跑偏"这些问题困扰的开发者。

我试过同时开三个 Claude Code 实例加两个 Codex 会话，结果第二天早上发现两个 Agent 在改同一个文件，第三个在反复重试一个已经失败的构建命令，账单还悄悄涨了一截。这就是 Paperclip 要解决的问题：当 AI 从"一个助手"变成"一支团队"，管理层的空白就暴露出来了。

Paperclip 本身是一个 Node.js server 加 React UI，把多个 AI Agent 放进同一个组织架构里，统一分配目标、追踪任务、管理成本、执行治理。它看起来像任务管理器，但底层多了一层"公司化"能力：组织架构、目标对齐、周期唤醒、成本预算、审批治理、审计追踪。

理解它的最好方式是一个类比：如果 Claude Code、Codex、Cursor 是员工，那么 Paperclip 就是公司。员工负责干活，公司负责定目标、分任务、控预算、做审批、留记录。Paperclip 官方 README 里明确写了它不是什么：不是 chatbot、不是 agent framework、不是 workflow builder、不是 prompt manager、不是 single-agent tool。这段话很关键，因为市面上绝大多数 AI 产品都在卷"单体能力"——能不能写代码、能不能调工具、能不能自动执行。但当你真的同时用多个 AI 时，难点早就不是"能不能写"，而是"怎么协调"。

Paperclip 的核心能力可以拆成六块。第一，Bring Your Own Agent，不强绑定任何 runtime，Claude Code、OpenClaw、Python 脚本、shell 命令、HTTP webhook 都能接入，原则上"只要能接收 heartbeat，就能被雇佣"。第二，Goal Alignment，每个任务都能追溯到更高层的公司目标，Agent 拿到的不只是一个孤立 ticket，而是理解"为什么要做"。第三，Heartbeats，Agent 按调度周期被唤醒，检查工作、继续推进，或者因为被分配任务、被 @ 提及而行动，更像"持续值班的员工"而不是一次性聊天窗口。第四，Cost Control，按 Agent 设月预算，80% 软提醒，100% 自动暂停，也可以手动 override。第五，Governance，用户是"董事会"，可以审批 hire、覆盖策略、暂停或终止 Agent。第六，Audit / Ticket System，提供 conversation tracing、tool-call tracing 和 audit log，追踪任务和决策链路。

这六块能力对应的其实是多 Agent 协作里最容易被忽视的管理层问题：协调、持续运行、治理、成本、目标。Paperclip 官方甚至专门强调它处理的是 atomic execution、persistent agent state、goal-aware execution 和 governance with rollback 这些编排细节。这也是它和很多"AI 自动化工具"最本质的差异——它不卷更强单体 Agent，它卷 orchestration。

那 Paperclip 需要自己接模型吗？不一定。官方明确说它不是 prompt manager，Agent 会带着自己的 prompts、models 和 runtimes 进来，Paperclip 管的是它们所在的组织。如果你接入的是现成 Agent，比如 Claude Code、Codex，模型通常已经在那个 Agent 里了，Paperclip 不需要再单独接模型。如果你自己写 adapter 接一个自定义 Python Agent 或 HTTP service，模型接入通常发生在你的 agent/runtime 层。所以更准确的说法是：Paperclip 接的是 Agent，不是必须直接接模型。

但这里有个现实问题：当你把多个 Agent 组织起来之后，每个 Agent 背后的模型调用通道怎么统一管理？如果每个 Agent 各自配一套 Key、各自走一条通道，成本追踪和权限治理就会散落在各处，Paperclip 的预算控制也会因为拿不到统一口径而打折扣。这就是为什么很多人在搭 Paperclip 的同时，会先把底层模型通道收敛到 TaoToken 这样的统一入口上——让 Paperclip 管组织，让 TaoToken 管通道，两层各司其职。

Paperclip 适合什么人？同时管理多个 AI Agent 的人、想做"AI 团队"而不是"单 AI 助手"的人、想让 Agent 长期自动运行但又不想完全失控的人、同时运营多个项目的人。它不适合什么人？官方写得很坦率：如果你只有一个 Agent，你大概率不需要 Paperclip；如果你有二十个，就很需要。门槛不在技术本身，而在于你是否真的已经进入"多 Agent 协作"阶段。

2. 接入前的准备：TaoToken 统一 Key 与 API 通道配置

在把 Paperclip 跑起来之前，先把底层模型通道准备好。这一步的逻辑是：Paperclip 负责编排 Agent，Agent 负责调用模型，而模型调用需要一个统一的 Key 和 Base URL。TaoToken 在这里扮演的角色就是统一通道——你不需要给每个 Agent 单独申请一套模型凭证，而是用一个 Key 走同一个入口，这样 Paperclip 的成本追踪和权限治理才有统一口径。

先明确三个核心参数，这三个东西在后面的配置里会反复出现：

第一步，获取 API Key。打开 TaoToken 控制台，进入 API Keys 页面，创建一个新的 Key。创建时建议按用途命名，比如paperclip-agent-pool，这样后面在 Paperclip 里做成本归因时能对得上。Key 只在创建时完整显示一次，复制后先存到安全的地方。

第二步，确认模型 ID。不同 Agent 对模型 ID 的写法要求不一样。Claude Code 系列通常用claude-sonnet-4-20250514这种带日期的完整 ID，Codex 系列用gpt-4o或o3这类短 ID。你可以在模型对话页面先手动发一条测试消息，确认这个 Model ID 在当前通道下能正常返回，再去配 Agent。

第三步，配置环境变量。最省事的做法是把 Base URL 和 Key 写进 shell 的环境变量，这样所有子进程都能继承：

export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_API_KEY="sk-你的实际Key"

如果你用的是 Claude Code，它认的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量名，所以需要额外做一层映射：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的实际Key"

如果你用的是 Codex，它读的是~/.codex/auth.json，这个文件的结构大概是这样：

{ "openai_api_key": "sk-你的实际Key", "base_url": "https://taotoken.net/api" }

注意base_url这里不要带尾部斜杠，也不要写成/v1结尾，TaoToken 的入口就是https://taotoken.net/api，路径拼接由客户端自己处理。

第四步，如果你用的是 Cline 或类似的 VS Code 插件，配置通常写在 settings JSON 里。以 Cline 为例，它的 MCP 配置和模型配置是分开的，模型部分需要填三个字段：

{ "apiProvider": "openai", "openAiBaseUrl": "https://taotoken.net/api", "openAiApiKey": "sk-你的实际Key", "openAiModelId": "claude-sonnet-4-20250514" }

这里 Base URL、Key、Model ID 三件套必须同时出现，缺一个都会导致请求失败。很多人只填了 Key 忘了改 Base URL，结果请求还是打到默认端点，报 401 或者 model not found。

第五步，如果你用 CC Switch 这类工具做多通道切换，它的配置文件通常是 TOML 格式，路径在~/.cc-switch/config.toml。一个可用的配置片段如下：

[[providers]] name = "taotoken" base_url = "https://taotoken.net/api" api_key = "sk-你的实际Key" model = "claude-sonnet-4-20250514"

配好之后，Paperclip 那边只需要知道 Agent 的可执行命令和它继承的环境变量，不需要在 Paperclip 内部再配一遍模型。这样分层的好处是：换模型通道时只改环境变量，Paperclip 的组织结构、预算、审批链都不用动。

最后提醒一点：不要把 Key 硬编码进 Paperclip 的配置文件或者提交到 Git。Paperclip 是 self-hosted 的，你的配置文件很可能跟着代码仓库走。用环境变量或者.env文件，并且把.env加进.gitignore。

3. 可复制配置：Paperclip 启动与 Agent 接入实操

配置准备好之后，开始跑 Paperclip。官方给的启动命令很直接：

npx paperclipai onboard --yes

这条命令会做几件事：拉取 Paperclip 的 Node.js server、初始化本地数据库、启动 React UI。官方说明它是 MIT 开源、self-hosted、不需要 Paperclip 账号、不会自动替你安装 Agent、可本地运行也可迁移到云端。本地单进程模式下，它会自动维护一个 embedded Postgres，你也可以接自己的 Postgres。

启动完成后，默认会在本地起一个 Web UI，通常是http://localhost:3000这个量级。打开之后你会看到组织架构视图、任务面板、Agent 列表、预算面板和审计日志入口。

接下来是接入 Agent。Paperclip 的接入逻辑是"只要能接收 heartbeat，就能被雇佣"。具体到操作层面，你需要在 Paperclip 里创建一个 Agent 条目，然后给它指定一个可执行命令或者一个 HTTP endpoint。

以接入 Claude Code 为例，创建一个 Agent 时填的核心字段包括：

{ "name": "frontend-engineer", "runtime": "shell", "command": "claude", "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的实际Key" }, "heartbeat_interval": "300s", "monthly_budget_usd": 50 }

这里的env字段就是关键。Paperclip 启动这个 Agent 时会把环境变量注入进去，Claude Code 读到ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY之后，所有模型请求就走 TaoToken 通道了。heartbeat_interval控制这个 Agent 多久被唤醒一次，monthly_budget_usd是它的月预算上限。

如果你接入的是一个自定义 Python Agent，配置类似，只是command换成python your_agent.py，然后在你的脚本里读环境变量：

import os from openai import OpenAI client = OpenAI( base_url=os.environ["TAOTOKEN_BASE_URL"], api_key=os.environ["TAOTOKEN_API_KEY"] ) response = client.chat.completions.create( model="claude-sonnet-4-20250514", messages=[{"role": "user", "content": "检查当前任务队列"}] ) print(response.choices[0].message.content)

如果你接入的是 HTTP webhook 类型的 Agent，Paperclip 会往你指定的 URL 发 heartbeat 请求，你的服务收到之后自己决定要不要调模型、调哪个模型。这种情况下模型通道的配置在你的服务内部完成，Paperclip 不关心。

创建完 Agent 之后，下一步是建组织架构。Paperclip 的 org chart 支持汇报线，你可以设一个 "CTO" Agent 下面挂三个 "engineer" Agent，再设一个 "reviewer" Agent 独立汇报。任务分配时，你可以指定某个任务由哪个角色接单，也可以让 Paperclip 按规则自动派单。

预算配置在 Agent 级别设置，但 Paperclip 也支持公司级别的总预算。建议的做法是：先给每个 Agent 设一个保守的月预算，比如 30 到 50 美元，然后设一个公司总预算作为兜底。80% 触发软提醒，100% 自动暂停。这个机制在多 Agent 场景下非常实用，因为一个跑飞的 Agent 一晚上烧掉几百美元的事情并不罕见。

审批治理这块，Paperclip 把用户设定成"董事会"。你可以在设置里指定哪些动作需要审批，比如 hire 新 Agent、修改预算、执行高风险命令。需要审批的动作会进入一个待办队列，你批准之后才继续执行。对于长期自动运行的 Agent 团队，这个能力比"多一个模型选项"重要得多。

审计日志默认开启，记录 conversation tracing、tool-call tracing 和决策链路。你可以在 UI 里按 Agent、按任务、按时间范围筛选。对于需要复盘"为什么这个任务跑了三天还没完成"的场景，这个日志比翻聊天记录有用得多。

最后一步是把任务和目标对齐。Paperclip 强调 Every task traces back to the company mission。创建任务时，除了填任务描述，还要选一个它归属的公司目标。这样 Agent 在执行时能看到上下文，而不是拿到一个孤立的 ticket。这个设计在实操中的价值是：当任务出现歧义时，Agent 可以回到目标层面做判断，而不是机械执行。

4. 验证请求：确认通道连通与 Agent 正常唤醒

配置写完不代表能跑通。在把 Agent 正式放进 Paperclip 之前，先用最小请求验证通道是通的。

第一步，用 curl 直接打 TaoToken 的 API，确认 Key 和 Base URL 没问题：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的实际Key" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10 }'

如果返回一个包含choices字段的 JSON，说明通道是通的。如果返回 401，说明 Key 有问题；如果返回 404 或者 model not found，说明 Model ID 写错了；如果连接超时，说明 Base URL 不对或者网络层有问题。

第二步，验证 Claude Code 是否读到了正确的环境变量。在终端里跑：

claude --version echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY | head -c 8

确认 Base URL 是https://taotoken.net/api，Key 的前几位对得上。然后跑一个最简单的 Claude Code 命令，比如让它读一个文件：

claude "读一下当前目录的 README.md，用一句话总结"

如果它能正常返回内容，说明 Claude Code 这条链路是通的。

第三步，在 Paperclip 里手动触发一次 Agent 的 heartbeat。Paperclip 的 UI 里通常有一个 "wake" 或者 "trigger" 按钮，点一下，然后看审计日志里有没有出现这次唤醒的记录。如果日志里出现了 heartbeat 事件，但 Agent 没有实际动作，说明 Agent 的命令配置有问题；如果连 heartbeat 事件都没有，说明 Paperclip 的调度器没跑起来。

第四步，检查预算面板。Paperclip 的预算面板会显示每个 Agent 的当前花费和剩余预算。如果你刚跑了一次测试请求，这里应该能看到一个很小的数字变化。如果预算面板一直是 0，说明 Paperclip 没有拿到模型调用的成本数据——这通常是因为 Agent 的模型调用没有走 Paperclip 能观测到的通道，或者成本回传的配置没开。

第五步，验证审计日志。跑一个稍微复杂点的任务，比如让 Agent 读一个文件然后写一个总结到另一个文件。任务完成后，在审计日志里应该能看到：任务创建、Agent 唤醒、工具调用（读文件）、模型调用、工具调用（写文件）、任务完成。如果中间缺了模型调用这一环，说明 tracing 没配好。

一个实测下来比较稳的验证顺序是：先 curl 通 API，再单跑 Agent 命令，再在 Paperclip 里手动唤醒，最后跑一个完整任务看审计日志。每一步都确认了再进下一步，出问题的时候定位范围小。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节列几个实际接入时高频出现的报错，以及对应的排查路径。

401 Unauthorized

这是最常见的报错。原因通常有三个：Key 没填对、Key 没被正确读取、Key 已经失效。排查顺序是：先用 curl 直接打 API 确认 Key 本身有效；然后检查 Agent 的环境变量注入是否成功，在 Agent 的启动脚本里加一行echo $ANTHROPIC_API_KEY | head -c 8看输出；最后检查 Paperclip 的 Agent 配置里env字段有没有写对，JSON 格式有没有语法错误导致整个 env 块被忽略。

注意一个坑：有些工具会优先读自己的配置文件而不是环境变量。比如 Codex 如果~/.codex/auth.json里有一个旧的 Key，它会用那个而不是环境变量里的。这种情况下要么更新 auth.json，要么删掉它让环境变量生效。

local proxy failed

这个报错通常出现在 Agent 试图通过一个本地代理访问模型通道时。原因可能是：Agent 配置里写了一个本地代理地址，但那个代理没启动；或者环境变量里残留了HTTP_PROXY/HTTPS_PROXY指向一个不存在的端口。排查方法是检查 Agent 的环境变量，把HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这几个变量清掉，然后确认 Base URL 直接指向https://taotoken.net/api，不经过任何中间层。

Error reading choices / reading 'choices'

这个报错的意思是客户端拿到了一个响应，但响应结构里没有choices字段。常见原因是：Base URL 写错了，请求打到了一个返回 HTML 错误页的地址，客户端试图把 HTML 当 JSON 解析；或者 Model ID 写错了，服务端返回了一个错误对象而不是正常的 completion 响应。排查方法是先用 curl 打一次同样的请求，看原始返回是什么。如果返回的是 HTML，说明 URL 不对；如果返回的是{"error": ...}，说明 Model ID 或者请求参数有问题。

OAuth 相关报错

如果你用的是 Claude Code 并且它试图走 OAuth 流程，可能会看到 OAuth token 相关的报错。原因是 Claude Code 默认可能走 Anthropic 的 OAuth 登录，而不是 API Key 模式。解决办法是确认ANTHROPIC_API_KEY已经设置，并且 Claude Code 的配置里没有残留的 OAuth token。有些版本需要显式指定用 API Key 模式，可以在启动参数里加--api-key或者检查配置文件里的auth_mode字段。

Agent 唤醒了但不干活

这个不是报错，但比报错更让人困惑。表现是审计日志里有 heartbeat 记录，但 Agent 没有任何工具调用或模型调用。原因通常是：Agent 的命令配置有问题，启动后立即退出；或者 Agent 在等待一个它永远等不到的输入。排查方法是手动在终端里跑一遍 Agent 的启动命令，看它是否正常进入交互状态。如果手动跑没问题但 Paperclip 里不行，检查 Paperclip 注入的环境变量是否完整，特别是工作目录和 PATH。

预算面板不更新

如果 Agent 在跑但预算面板一直是 0，说明成本数据没有回传。Paperclip 的成本追踪依赖于 Agent 上报或者通道侧的回传。如果你用的是 TaoToken 统一通道，确认 Agent 的模型调用确实走了这个通道，而不是某个本地缓存或者备用端点。另外检查 Paperclip 的审计日志里有没有模型调用记录，如果没有，说明 tracing 层没接上。

排查这些问题的通用思路是：先确认最小链路（curl 打 API）是通的，再确认 Agent 单独跑是通的，最后确认 Paperclip 里的集成是通的。三层都通了，剩下的就是配置细节问题。

6. 从 Paperclip 到 TaoToken：把编排层和通道层分开

Paperclip 的价值不在于替代 Cursor、Claude Code、Codex，而在于把这些工具从"散兵游勇"变成"一个组织"。它想做的不是最强员工，而是 AI 时代的公司操作系统。但一个公司操作系统要跑得稳，底层的模型通道必须统一、可观测、可治理。

这就是为什么建议把编排层和通道层分开：Paperclip 管组织架构、任务分配、预算审批、审计追踪；TaoToken 管模型调用的统一入口、Key 管理、成本归因。两层各司其职，换模型的时候只动通道层，Paperclip 里的组织结构和治理规则都不用改。

如果你已经在用多个 AI coding 工具，并且开始遇到"谁在干什么、花了多少钱、任务有没有跑偏"这些问题，可以先从统一通道开始。把 Claude Code、Codex、Cline 这些工具的 Base URL 都指向https://taotoken.net/api，用一个 Key 管理所有调用，然后再考虑要不要上 Paperclip 做编排。通道统一是编排的前提，没有统一通道，编排层的预算控制和审计追踪都是空中楼阁。

具体操作上，先去 API Keys 页面创建一个 Key，然后按第 2 节的配置把环境变量设好，用第 4 节的 curl 命令验证连通。确认通道没问题之后，再跑npx paperclipai onboard --yes启动 Paperclip，按第 3 节的配置接入 Agent。整个过程的核心就是三件套：Base URL 填https://taotoken.net/api，Key 填你创建的那个，Model ID 按 Agent 的要求填对应的模型标识。

接入文档里有更详细的参数说明和不同客户端的配置示例，遇到报错的时候可以对照第 5 节先自查一遍。如果 curl 能通但 Agent 不通，问题大概率在环境变量注入或者客户端配置文件上；如果 curl 都不通，问题在 Key 或者 Base URL 上。按这个顺序排查，大部分问题都能定位到。