1. Paperclip 是什么Agent Framework 里的“公司控制面”到底解决什么问题Paperclip 是一个开源的 Agent Framework定位是“给工作中的 AI agents 用的应用”。它用 Node.js server React UI 把一组协同工作的 AI 代理组织成一个可管理的体系核心不是单个聊天机器人而是把多个代理当成一家“公司”来编排。你可以把它理解成 Agent 团队的调度中枢目标、组织架构、预算、审批、任务层级、心跳执行和治理都放在同一个控制面里。它和常见的单代理工具差别很大。像 Claude Code、Codex、Cursor、Bash、HTTP 这类运行体只要“可被调用、可被观察、可被授权”就能被 Paperclip 统一接入并协调。仓库 README 里有一句很直白的概括“If OpenClaw is an employee, Paperclip is the company.” 这句话点明了它的角色——不是替代某个编辑器或聊天窗口而是管理一整支代理团队。适合谁用如果你同时开着好几个 Claude Code 终端、已经分不清谁在做什么如果你想让代理 24/7 自治运行但仍希望随时审计、插手或叫停如果你对 token 成本敏感需要给每个代理设置月度预算并在达到上限后自动停止如果你想从一个具体目标出发比如“3 个月内做出 100 万 MRR 的 AI 笔记应用”搭出一套持续推进的工作流那 Paperclip 就是为你准备的。它的几个关键特点值得先记住以“公司”为第一组织单元一个实例可运行多家公司且数据隔离任务层级化每个任务必须追溯至上级任务并最终关联公司总目标内置心跳机制代理按计划醒来检查工作、执行动作后退出也支持任务分配或 提及这类事件触发内置预算限制可为每个代理设置月度预算达到上限自动停止提供完整的 Tool-Call Tracing 和不可变审计日志支持董事会级治理可审批招聘、覆盖策略、暂停或终止任一代理。部署上它是本地优先、云端兼容。典型本地部署是单个 Node.js 进程管理 Embedded Postgres 和本地文件存储生产环境可对接自有 Postgres并支持 local_trusted 和 authenticated 两种运行模式。最低要求是 Node.js 20、pnpm 9.15。下面我从环境准备开始一步步带你把它跑起来并接入 TaoToken 统一 Key/API 通道完成模型调用。2. 前置准备Node.js 20、pnpm 9.15 与 TaoToken 统一 Key 配置在动手之前先把两件事准备好本地运行环境和模型调用通道。Paperclip 本身是编排平台它需要调用底层模型来完成代理的推理所以你需要一个稳定的 API 入口。这里我用 TaoToken 作为统一 Key/API 通道把模型调用集中管理避免每个代理各配一套 Key 导致混乱。先确认本地环境。打开终端执行node -v pnpm -v如果 Node.js 低于 20建议用 nvm 或官方安装包升级。pnpm 如果没装可以用 corepack 启用corepack enable corepack prepare pnpmlatest --activatepnpm 版本要 9.15低于这个版本在安装依赖时可能报 lockfile 不兼容。确认无误后去 TaoToken 控制台创建一个 API Key。访问 https://taotoken.net/api-keys 生成 Key然后到接入文档 https://taotoken.net/doc 核对最新的 Base URL 和可用 Model ID。TaoToken 的 API 入口是 https://taotoken.net/api这个地址在配置里会反复用到。这里要强调一个概念Paperclip 里的每个代理运行时比如 Claude Code session、Codex instance、Python 脚本都需要一个模型调用出口。如果你给每个运行时单独配 Key后期做预算管控和审计时会非常痛苦。用 TaoToken 统一 Key 的好处是所有代理的模型请求都走同一个通道你只需要在环境变量或配置文件里维护一份凭证切换模型时改一个 Model ID 即可。我建议把凭证放在项目根目录的.env文件里不要硬编码进源码。一个最小可用的.env长这样# TaoToken 统一调用通道 TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL_IDclaude-sonnet-4-5注意 Base URL 不要带末尾斜杠Model ID 要和控制台里列出的名称完全一致大小写敏感。如果你用的是 Claude Code 这类需要 Anthropic 兼容协议的运行时Base URL 和 Model ID 的写法可能略有差异具体以接入文档为准。配置完成后可以先单独验证一下通道是否通curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500能返回模型列表就说明 Key 和网络都没问题。这一步别跳过后面 Paperclip 报错时你能快速判断是通道问题还是框架问题。3. 可复制配置Paperclip 安装、onboard 与 settings 片段环境就绪后开始安装。README 的 Quickstart 非常直接npx paperclipai onboard --yes这是开源、自托管、无需 Paperclip 账号的启动方式默认走 trusted local loopback mode方便快速完成第一次运行。如果你想显式进入其他绑定模式可以加--bind参数npx paperclipai onboard --yes --bind lan npx paperclipai onboard --yes --bind tailnet如果你已经配置过 Paperclip再次运行 onboard 会保留原有配置想改设置则用paperclipai configure。如果你更愿意直接跑源码做本地开发README 给出的方式是git clone https://github.com/paperclipai/paperclip.git cd paperclip pnpm install pnpm dev这样会启动 API server默认地址是 http://localhost:3100并且 embedded PostgreSQL 会自动创建不需要额外数据库初始化。安装过程中有一个很常见的坑如果你使用了私有 npm 源npx 可能会把 paperclipai 解析到私有源而报 E404。官方给出的规避方式是强制使用公共 npm registrynpx --registry https://registry.npmjs.org paperclipai onboard --yes接下来是关键的模型接入配置。Paperclip 支持多种运行时这里以 Claude Code 风格的 settings 为例把 TaoToken 的 Base URL、Key、Model ID 三件套写全。在项目目录下创建或编辑.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的实际Key, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [Bash, Read, Write, Edit] } }如果你用的是 Codex 风格的运行时配置写在~/.codex/auth.json里同样三件套要齐全{ base_url: https://taotoken.net/api, api_key: sk-你的实际Key, model: gpt-5-codex }对于 Cline MCP 这类通过 MCP 协议接入的场景配置片段如下{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的实际Key, TAOTOKEN_MODEL_ID: claude-sonnet-4-5 } } } }三件套的核心逻辑是一致的Base URL 指向 https://taotoken.net/apiKey 用你在控制台生成的那一串Model ID 用文档里确认可用的名称。任何一处写错代理启动后都会在调用模型时失败。配置完成后回到 Paperclip 的 UI默认 http://localhost:3100在创建代理时选择对应的运行时适配器它就会读取这些配置。4. 验证请求与成功结果从最小示例到多步任务编排配置写好后先跑一个最小可运行示例验证整条链路。在 Paperclip UI 里创建一个 company定义一个 company goal比如“整理一份本周技术动态摘要”。然后创建一个 CEO 代理给它配置 Claude Code 运行时预算设为 5 美元/月。点击启动后代理会按心跳机制醒来执行任务。你也可以先用命令行验证模型通道是否被 Paperclip 正确读取。在项目目录下执行pnpm dev观察启动日志正常会看到 API server 监听 3100 端口、embedded PostgreSQL 初始化完成、以及运行时适配器加载成功的提示。如果日志里出现local proxy failed或reading choices之类的字样说明模型调用没走通回到第 5 节排查。最小示例跑通后可以试一个多步任务编排的案例。假设目标是“调研三个竞品并输出对比表”你可以这样拆解CEO 代理接收总目标拆出三个子任务分别分配给三个研究代理每个研究代理用不同的运行时一个 Claude Code、一个 Codex、一个 Python 脚本最后 CEO 汇总结果。在 Paperclip 里每个子任务都必须追溯至上级任务并最终关联公司总目标这样代理始终清楚“我为什么在做这件事”。实测下来心跳机制是这套编排的关键。代理默认按 scheduled heartbeats 和 event-based triggers 工作比如任务分配或 提及。你可以让代理 24/7 自治运行但仍能在需要时审计工作、插手或叫停。每次对话追踪、每个决策可解释Tool-Call Tracing 和不可变审计日志都会记录下来。如果某个代理的月度预算达到上限它会自动停止避免失控消耗。验证成功的标志有几个UI 里能看到任务层级树、每个代理的执行状态和成本累计审计日志里有完整的工具调用记录模型返回的结果符合预期。如果这些都正常说明 Paperclip TaoToken 的整条链路已经打通。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节把最容易踩的坑集中列出来对照真实报错给出验证动作。401 Unauthorized最常见的原因是 Key 写错或过期。检查.env、settings.json、auth.json里的 Key 是否和控制台一致注意不要有多余空格或换行。如果 Key 没问题检查 Base URL 是否写成了https://taotoken.net/api/多了末尾斜杠有些运行时会因此拼接出错误路径。验证动作用第 2 节的 curl 命令单独测通道能返回模型列表就说明 Key 有效。local proxy failed这个报错通常出现在运行时适配器尝试通过本地代理转发请求时。检查你的环境变量里是否有残留的HTTP_PROXY或HTTPS_PROXY设置它们可能干扰 Paperclip 的本地回环通信。验证动作临时 unset 这些变量后重启pnpm dev观察报错是否消失。另外确认 3100 端口没有被其他进程占用。reading choices 报错这通常意味着模型返回的响应结构不符合运行时预期多半是 Model ID 写错了或者 Base URL 指向的端点不兼容当前协议。验证动作核对 Model ID 是否在 TaoToken 文档的可用列表里确认运行时用的是 Anthropic 兼容协议还是 OpenAI 兼容协议两者端点路径不同。OAuth 相关报错如果你用的是 Claude Code 或 Codex 的 OAuth 登录模式它可能会尝试走官方登录流程而不是 API Key。验证动作确认配置里用的是ANTHROPIC_API_KEY而不是 OAuth token必要时清理~/.claude或~/.codex下的缓存凭证强制走 API Key 模式。E404 私有源问题前面提过npx 解析到私有源会报 E404。验证动作加--registry https://registry.npmjs.org参数重试。pnpm 版本不兼容低于 9.15 会报 lockfile 错误。验证动作pnpm -v确认版本用 corepack 升级。排查时记住一个原则先隔离通道问题再查框架问题。用 curl 测 TaoToken 通道用pnpm dev看 Paperclip 启动日志两者都正常再查运行时适配器配置。这样能快速定位问题在哪一层。6. 长期编码与 Agent 编排把 TaoToken 通道用稳的实用建议跑通之后如果你打算长期用 Paperclip 做 Agent 编排有几个经验值得参考。第一把 TaoToken 的 Key 和 Base URL 统一放在一个环境变量文件里所有运行时适配器都引用同一份切换模型时只改 Model ID。第二给每个代理设置合理的月度预算Paperclip 的 stop-at-limit 机制能有效防止失控消耗尤其是多个代理并行跑心跳任务时。第三善用审计日志每次任务执行后回看 Tool-Call Tracing能发现代理是否在重复无效操作。如果你需要更稳定的长期编码或 Agent 运行通道可以了解 TaoToken 的 Coding Plan它针对高频调用场景做了优化。模型对话验证可以去 https://taotoken.net/models 直接测试接入文档在 https://taotoken.net/doc控制台在 https://taotoken.net/consoleAPI Key 管理在 https://taotoken.net/api-keys。把这些地址收藏好配置和排障时会反复用到。最后提醒一点Paperclip 是编排平台不是编辑器替代品也不是代码审查工具。它的价值在于把多个代理、目标、预算和治理放在同一个控制面里管理。当你同时跑着好几个代理、开始分不清谁在做什么的时候就是它发挥作用的时候。