Paperclip

环境搭建（Setup）

首次使用时，请阅读 setup.md 获取集成指引。

使用场景（When to Use）

当用户需要安装、运维或评估 Paperclip 作为 AI 智能体团队的控制平面（control plane）时使用。适用于本地优先（local-first）部署、智能体公司（agent-company）架构设计、适配器（adapter）选型、OpenClaw 集成、CLI 操作以及基于 API 的协同调度。

架构说明（Architecture）

技能记忆（Skill memory）存于 ~/paperclip/ 目录下。Paperclip 应用数据通常存于 ~/.paperclip/instances/ 目录中。若 ~/paperclip/ 不存在，请运行 setup.md 中的初始化流程。目录结构详见 memory-template.md。

~/paperclip/
├── memory.md            # 运维人员上下文、活跃实例列表、适配器偏好设置
├── companies.md         # 公司名称、目标与状态快照
├── commands.md          # 已验证有效的 CLI/API 片段（复用命令）
└── notes.md             # 待解问题、阻塞项、迁移备注

快速参考（Quick Reference）

系统要求（Requirements）

• Node.js 20+：用于官方 paperclipai 包及本地服务端
• pnpm 9.15+：用于基于代码仓库的工作流
• curl：用于直接调用 API 及自动化脚本
• 仅需提供所启用适配器对应的服务商凭证（Provider credentials）

核心原则（Core Rules）

1. 将 Paperclip 视为控制平面

• 使用 Paperclip 统一管理公司（companies）、智能体（agents）、目标（goals）、问题（issues）、审批（approvals）和预算（budgets）。
• 不应将其视为执行具体业务逻辑的领域工作器（domain worker）；实际任务由接入的运行时（runtimes）完成。

2. 默认采用本地优先策略，除非用户已具备基础设施

• 首个可用实例推荐使用 npx paperclipai onboard --yes 启动。
• 在临时环境测试或需严格隔离时，使用 --data-dir 参数指定独立数据目录。

3. 先建模公司结构，再启动智能体

• 在唤醒多个智能体前，需明确定义公司目标、汇报关系（reports-to）、工作区（workspaces）及问题流转机制（issue flow）。
• 当权责归属、预算分配与升级路径（escalation paths）显式化后，Paperclip 的价值才真正显现。

4. 按执行边界选择适配器

• 若智能体需与 Paperclip 运行在同一主机上，请选用 codex_local 或 claude_local。
• 若 OpenClaw 部署在控制平面之外，并需以“雇员”身份被调度，则选用 openclaw_gateway。

5. 充分利用心跳机制、审批关卡与预算管控

• 心跳（heartbeats）是默认执行循环；智能体无需持续运行即可保持协同。
• 审批门禁（approval gates）与支出上限（spend caps）是核心运营控制手段，而非可选附加功能。

6. 使用 CLI 与 API 实现可重复操作

• 创建公司、问题、审批及唤醒指令等操作，应优先采用粒度小、可审计的命令。
• 若用户偏好通过 OpenClaw、Codex 或 Claude 进行人工对话，请将该交互保留在对应界面，而 Paperclip 始终作为唯一可信数据源（source of truth）。

常见误区（Common Traps）

• 将 Paperclip 当作聊天 UI 使用 → 忽略其组织架构、治理机制与成本控制层，丧失核心价值。
• 在未定义汇报关系、工作区与预算前即启动大量智能体 → 系统退化为无序并行的多个标签页（unmanaged parallel tabs）。
• 在 OpenClaw Docker 容器内使用 localhost → 容器将解析为自身，而非 Paperclip 所在宿主机。
• 未安装并认证本地 CLI 即期望 Codex 或 Claude 适配器正常工作 → 心跳在有效任务启动前即失败。
• 跳过问题检出（issue checkout）语义 → 多个智能体可能在 Paperclip 工作流之外并发处理同一任务。

外部端点（External Endpoints）

除非用户显式配置远程部署或模型服务商，否则不应访问其他任何外部端点。

安全与隐私（Security & Privacy）

离开本机的数据：

• 发往用户选定的 Paperclip API 基地址的请求
• 启用 OpenClaw 适配器时，发往所配置 OpenClaw 网关的请求
• 用户安装并授权的智能体运行时所产生的任意服务商流量

保留在本地的数据：

• 存于 ~/.paperclip/instances/ 的 Paperclip 实例状态
• 存于 ~/paperclip/ 的技能记忆
• 关联至项目的本地工作区（local workspaces）

本技能明确不执行以下行为：

• 不强制要求 Paperclip 云账户（cloud account）
• 不在命令或记忆文件中暴露密钥（secrets）
• 不默认假设存在公开部署（public deployment）

可信性声明（Trust）

使用本技能时，所有运营数据将发送至用户所配置的 Paperclip 部署及智能体适配器。  
仅当您信任该部署本身、其存储系统，以及背后所依赖的模型服务商时，方可安装使用。

相关技能（Related Skills）

若用户确认安装，可通过 clawhub install 命令获取：

• agent — 通用智能体执行与委托模式
• agents — 多智能体协同与角色设计
• company — 公司级战略与运营架构
• workflow — 可复用的运营工作流与交接机制
• api — 直接 API 调用、载荷设计与 HTTP 故障排查

反馈（Feedback）

• 若本技能有用：请执行 clawhub star paperclip
• 保持更新：请定期执行 clawhub sync