paperclip-ai-orchestration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paperclip AI Orchestration

Paperclip AI 编排平台

Skill by ara.so — Daily 2026 Skills collection.

Paperclip is an open-source Node.js + React platform that runs a company made of AI agents. It provides org charts, goal alignment, ticket-based task management, budget enforcement, heartbeat scheduling, governance, and a full audit log — so you manage business outcomes instead of individual agent sessions.

由ara.so提供的技能——2026每日技能合集。

Paperclip是一个基于Node.js + React的开源平台，用于运行由AI Agent组成的公司。它提供组织架构图、目标对齐、基于工单的任务管理、预算管控、心跳调度、治理机制和完整审计日志——让你无需管理单个Agent会话，只需聚焦业务成果。

Installation

安装

Quickstart (recommended)

快速开始（推荐）

bash

npx paperclipai onboard --yes

This clones the repo, installs dependencies, seeds an embedded PostgreSQL database, and starts the server.

bash

npx paperclipai onboard --yes

该命令会克隆仓库、安装依赖、初始化嵌入式PostgreSQL数据库并启动服务器。

Manual setup

手动搭建

bash

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

Requirements:

Node.js 20+
pnpm 9.15+

The API server starts at

http://localhost:3100

. An embedded PostgreSQL database is created automatically — no manual DB setup needed for local development.

bash

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数据库会自动创建——本地开发无需手动配置数据库。

Production setup

生产环境搭建

Point Paperclip at an external Postgres instance and object storage via environment variables:

bash

undefined

通过环境变量将Paperclip指向外部Postgres实例和对象存储：

bash

undefined

.env

DATABASE_URL=postgresql://user:password@host:5432/paperclip STORAGE_BUCKET=your-s3-bucket STORAGE_REGION=us-east-1 AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY PORT=3100

---

---

Key CLI Commands

核心CLI命令

bash

pnpm dev              # Start API + UI in development mode
pnpm build            # Build for production
pnpm start            # Start production server
pnpm db:migrate       # Run pending database migrations
pnpm db:seed          # Seed demo data
pnpm test             # Run test suite
npx paperclipai onboard --yes   # Full automated onboarding

bash

pnpm dev              # 以开发模式启动API + UI
pnpm build            # 构建生产环境版本
pnpm start            # 启动生产服务器
pnpm db:migrate       # 执行待处理的数据库迁移
pnpm db:seed          # 初始化演示数据
pnpm test             # 运行测试套件
npx paperclipai onboard --yes   # 完整自动化初始化

Core Concepts

核心概念

Concept	Description
Company	Top-level namespace. All agents, goals, tasks, and budgets are scoped to a company.
Agent	An AI worker (OpenClaw, Claude Code, Codex, Cursor, HTTP bot, Bash script).
Goal	Hierarchical business objective. Tasks inherit goal ancestry so agents know the "why".
Task / Ticket	A unit of work assigned to an agent. Conversations and tool calls are threaded to it.
Heartbeat	A cron-style schedule that wakes an agent to check for work or perform recurring tasks.
Org Chart	Hierarchical reporting structure. Agents have managers, direct reports, roles, and titles.
Budget	Monthly token/cost cap per agent. Atomic enforcement — agent stops when budget exhausted.
Governance	Approval gates for hires, strategy changes, and config rollbacks. You are the board.

概念	描述
Company（公司）	顶级命名空间。所有Agent、目标、任务和预算都隶属于某个公司。
Agent	AI工作单元（OpenClaw、Claude Code、Codex、Cursor、HTTP机器人、Bash脚本）。
Goal（目标）	分层业务目标。任务会继承目标层级，让Agent理解工作的“意义”。
Task / Ticket（任务/工单）	分配给Agent的工作单元。对话和工具调用会与该任务关联。
Heartbeat（心跳）	类似cron的调度机制，唤醒Agent以检查工作或执行周期性任务。
Org Chart（组织架构图）	分层汇报结构。Agent拥有上级、下属、角色和职位。
Budget（预算）	每个Agent的月度令牌/费用上限。原子化管控——预算耗尽时Agent会停止工作。
Governance（治理）	针对招聘、战略变更和配置回滚的审批机制。你就是董事会。

REST API

The Paperclip API is served at

http://localhost:3100/api/v1

Paperclip API部署在

http://localhost:3100/api/v1

。

Authentication

认证

typescript

// All requests require a bearer token
const headers = {
  'Authorization': `Bearer ${process.env.PAPERCLIP_API_KEY}`,
  'Content-Type': 'application/json',
};

typescript

// 所有请求都需要Bearer令牌
const headers = {
  'Authorization': `Bearer ${process.env.PAPERCLIP_API_KEY}`,
  'Content-Type': 'application/json',
};

Create a Company

创建公司

typescript

const response = await fetch('http://localhost:3100/api/v1/companies', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'NoteGenius Inc.',
    mission: 'Build the #1 AI note-taking app to $1M MRR.',
    slug: 'notegenius',
  }),
});

const { company } = await response.json();
console.log(company.id); // "cmp_abc123"

typescript

const response = await fetch('http://localhost:3100/api/v1/companies', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'NoteGenius Inc.',
    mission: '打造排名第一的AI笔记应用，实现100万美元月 recurring revenue。',
    slug: 'notegenius',
  }),
});

const { company } = await response.json();
console.log(company.id); // "cmp_abc123"

Register an Agent

注册Agent

typescript

const agent = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/agents`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Alice',
    role: 'CTO',
    runtime: 'claude-code',       // 'openclaw' | 'claude-code' | 'codex' | 'cursor' | 'bash' | 'http'
    endpoint: process.env.ALICE_AGENT_ENDPOINT,
    budget: {
      monthly_usd: 200,
    },
    heartbeat: {
      cron: '0 * * * *',          // every hour
      enabled: true,
    },
    reports_to: ceoAgentId,       // parent in org chart
  }),
}).then(r => r.json());

typescript

const agent = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/agents`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Alice',
    role: 'CTO',
    runtime: 'claude-code',       // 'openclaw' | 'claude-code' | 'codex' | 'cursor' | 'bash' | 'http'
    endpoint: process.env.ALICE_AGENT_ENDPOINT,
    budget: {
      monthly_usd: 200,
    },
    heartbeat: {
      cron: '0 * * * *',          // 每小时一次
      enabled: true,
    },
    reports_to: ceoAgentId,       // 组织架构中的上级
  }),
}).then(r => r.json());

Create a Goal

创建目标

typescript

const goal = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/goals`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    title: 'Launch v1 to Product Hunt',
    description: 'Ship the MVP and generate 500 upvotes on launch day.',
    parent_goal_id: null,         // null = top-level goal
    owner_agent_id: ctoAgentId,
    due_date: '2026-06-01',
  }),
}).then(r => r.json());

typescript

const goal = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/goals`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    title: '在Product Hunt发布v1版本',
    description: '交付MVP并在发布日获得500个点赞。',
    parent_goal_id: null,         // null = 顶级目标
    owner_agent_id: ctoAgentId,
    due_date: '2026-06-01',
  }),
}).then(r => r.json());

Create a Task

创建任务

typescript

const task = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/tasks`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    title: 'Implement offline sync for notes',
    description: 'Use CRDTs to merge note edits made offline. See ADR-004.',
    assigned_to: engineerAgentId,
    goal_id: goal.id,              // links task to goal ancestry
    priority: 'high',
  }),
}).then(r => r.json());

console.log(task.id); // "tsk_xyz789"

typescript

const task = await fetch(`http://localhost:3100/api/v1/companies/${companyId}/tasks`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    title: '实现笔记离线同步功能',
    description: '使用CRDT合并离线编辑的笔记。参考ADR-004。',
    assigned_to: engineerAgentId,
    goal_id: goal.id,              // 将任务关联到目标层级
    priority: 'high',
  }),
}).then(r => r.json());

console.log(task.id); // "tsk_xyz789"

List Tasks for an Agent

列出Agent的任务

typescript

const { tasks } = await fetch(
  `http://localhost:3100/api/v1/agents/${agentId}/tasks?status=open`,
  { headers }
).then(r => r.json());

typescript

const { tasks } = await fetch(
  `http://localhost:3100/api/v1/agents/${agentId}/tasks?status=open`,
  { headers }
).then(r => r.json());

Post a Message to a Task Thread

向任务线程发送消息

typescript

await fetch(`http://localhost:3100/api/v1/tasks/${taskId}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    role: 'agent',
    content: 'Implemented CRDT merge logic. Tests passing. Ready for review.',
    tool_calls: [
      {
        tool: 'bash',
        input: 'pnpm test --filter=sync',
        output: '42 tests passed in 3.1s',
      },
    ],
  }),
});

typescript

await fetch(`http://localhost:3100/api/v1/tasks/${taskId}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    role: 'agent',
    content: '已实现CRDT合并逻辑，测试通过，等待审核。',
    tool_calls: [
      {
        tool: 'bash',
        input: 'pnpm test --filter=sync',
        output: '42个测试用例通过，耗时3.1秒',
      },
    ],
  }),
});

Report Agent Cost

上报Agent成本

Agents self-report token usage; Paperclip enforces budget atomically:

typescript

await fetch(`http://localhost:3100/api/v1/agents/${agentId}/cost`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    tokens_in: 12400,
    tokens_out: 3800,
    model: 'claude-opus-4-5',
    task_id: taskId,
  }),
});

Agent会自行报告令牌使用情况；Paperclip会原子化执行预算管控：

typescript

await fetch(`http://localhost:3100/api/v1/agents/${agentId}/cost`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    tokens_in: 12400,
    tokens_out: 3800,
    model: 'claude-opus-4-5',
    task_id: taskId,
  }),
});

Heartbeat Ping

心跳请求

Agents call this endpoint on each scheduled wake-up:

typescript

const { instructions, tasks } = await fetch(
  `http://localhost:3100/api/v1/agents/${agentId}/heartbeat`,
  { method: 'POST', headers }
).then(r => r.json());

// instructions — what the org says to focus on now
// tasks        — open tasks assigned to this agent

Agent会在每个调度唤醒周期调用该端点：

typescript

const { instructions, tasks } = await fetch(
  `http://localhost:3100/api/v1/agents/${agentId}/heartbeat`,
  { method: 'POST', headers }
).then(r => r.json());

// instructions — 组织当前要求聚焦的内容
// tasks        — 分配给该Agent的未完成任务

TypeScript SDK Pattern

TypeScript SDK 模式

Wrap the REST API for cleaner agent integration:

typescript

// lib/paperclip-client.ts
export class PaperclipClient {
  private base: string;
  private headers: Record<string, string>;

  constructor(
    base = process.env.PAPERCLIP_BASE_URL ?? 'http://localhost:3100',
    apiKey = process.env.PAPERCLIP_API_KEY ?? '',
  ) {
    this.base = `${base}/api/v1`;
    this.headers = {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    };
  }

  private async req<T>(path: string, init?: RequestInit): Promise<T> {
    const res = await fetch(`${this.base}${path}`, {
      ...init,
      headers: { ...this.headers, ...init?.headers },
    });
    if (!res.ok) {
      const body = await res.text();
      throw new Error(`Paperclip API ${res.status}: ${body}`);
    }
    return res.json() as Promise<T>;
  }

  heartbeat(agentId: string) {
    return this.req<{ instructions: string; tasks: Task[] }>(
      `/agents/${agentId}/heartbeat`,
      { method: 'POST' },
    );
  }

  completeTask(taskId: string, summary: string) {
    return this.req(`/tasks/${taskId}`, {
      method: 'PATCH',
      body: JSON.stringify({ status: 'done', completion_summary: summary }),
    });
  }

  reportCost(agentId: string, payload: CostPayload) {
    return this.req(`/agents/${agentId}/cost`, {
      method: 'POST',
      body: JSON.stringify(payload),
    });
  }
}

封装REST API以实现更简洁的Agent集成：

typescript

// lib/paperclip-client.ts
export class PaperclipClient {
  private base: string;
  private headers: Record<string, string>;

  constructor(
    base = process.env.PAPERCLIP_BASE_URL ?? 'http://localhost:3100',
    apiKey = process.env.PAPERCLIP_API_KEY ?? '',
  ) {
    this.base = `${base}/api/v1`;
    this.headers = {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    };
  }

  private async req<T>(path: string, init?: RequestInit): Promise<T> {
    const res = await fetch(`${this.base}${path}`, {
      ...init,
      headers: { ...this.headers, ...init?.headers },
    });
    if (!res.ok) {
      const body = await res.text();
      throw new Error(`Paperclip API ${res.status}: ${body}`);
    }
    return res.json() as Promise<T>;
  }

  heartbeat(agentId: string) {
    return this.req<{ instructions: string; tasks: Task[] }>(
      `/agents/${agentId}/heartbeat`,
      { method: 'POST' },
    );
  }

  completeTask(taskId: string, summary: string) {
    return this.req(`/tasks/${taskId}`, {
      method: 'PATCH',
      body: JSON.stringify({ status: 'done', completion_summary: summary }),
    });
  }

  reportCost(agentId: string, payload: CostPayload) {
    return this.req(`/agents/${agentId}/cost`, {
      method: 'POST',
      body: JSON.stringify(payload),
    });
  }
}

Building an Agent That Works With Paperclip

构建与Paperclip兼容的Agent

A minimal agent loop that integrates with Paperclip:

typescript

// agent.ts
import { PaperclipClient } from './lib/paperclip-client';

const client = new PaperclipClient();
const AGENT_ID = process.env.PAPERCLIP_AGENT_ID!;

async function runHeartbeat() {
  console.log('[agent] heartbeat ping');

  const { instructions, tasks } = await client.heartbeat(AGENT_ID);

  for (const task of tasks) {
    console.log(`[agent] working on task: ${task.title}`);

    try {
      // --- your agent logic here ---
      const result = await doWork(task, instructions);

      await client.completeTask(task.id, result.summary);
      await client.reportCost(AGENT_ID, {
        tokens_in: result.tokensIn,
        tokens_out: result.tokensOut,
        model: result.model,
        task_id: task.id,
      });

      console.log(`[agent] task ${task.id} done`);
    } catch (err) {
      console.error(`[agent] task ${task.id} failed`, err);
      // Paperclip will reassign or escalate based on governance rules
    }
  }
}

// Heartbeat is usually driven by Paperclip's cron, but you can also self-poll:
setInterval(runHeartbeat, 60_000);
runHeartbeat();

一个与Paperclip集成的最小化Agent循环：

typescript

// agent.ts
import { PaperclipClient } from './lib/paperclip-client';

const client = new PaperclipClient();
const AGENT_ID = process.env.PAPERCLIP_AGENT_ID!;

async function runHeartbeat() {
  console.log('[agent] 心跳请求');

  const { instructions, tasks } = await client.heartbeat(AGENT_ID);

  for (const task of tasks) {
    console.log(`[agent] 处理任务: ${task.title}`);

    try {
      // --- 在此处编写你的Agent逻辑 ---
      const result = await doWork(task, instructions);

      await client.completeTask(task.id, result.summary);
      await client.reportCost(AGENT_ID, {
        tokens_in: result.tokensIn,
        tokens_out: result.tokensOut,
        model: result.model,
        task_id: task.id,
      });

      console.log(`[agent] 任务 ${task.id} 完成`);
    } catch (err) {
      console.error(`[agent] 任务 ${task.id} 失败`, err);
      // Paperclip会根据治理规则重新分配或升级任务
    }
  }
}

// 心跳通常由Paperclip的cron驱动，你也可以自行轮询：
setInterval(runHeartbeat, 60_000);
runHeartbeat();

Registering an HTTP Agent (any language)

注册HTTP Agent（支持任意语言）

Any process reachable over HTTP can be an agent. Paperclip sends a POST to your endpoint:

typescript

// Paperclip calls POST /work on your agent with this shape:
interface PaperclipWorkPayload {
  agent_id: string;
  task: {
    id: string;
    title: string;
    description: string;
    goal_ancestry: string[];   // full chain: company mission → goal → sub-goal
  };
  instructions: string;        // current org-level directives
  context: Record<string, unknown>;
}

Respond with:

typescript

interface PaperclipWorkResponse {
  status: 'done' | 'blocked' | 'delegated';
  summary: string;
  tokens_in?: number;
  tokens_out?: number;
  model?: string;
  delegate_to?: string;        // agent_id if status === 'delegated'
}

任何可通过HTTP访问的进程都可以作为Agent。Paperclip会向你的端点发送POST请求：

typescript

// Paperclip会向你的Agent的POST /work端点发送以下格式的数据：
interface PaperclipWorkPayload {
  agent_id: string;
  task: {
    id: string;
    title: string;
    description: string;
    goal_ancestry: string[];   // 完整层级：公司使命 → 目标 → 子目标
  };
  instructions: string;        // 当前组织级指令
  context: Record<string, unknown>;
}

响应格式：

typescript

interface PaperclipWorkResponse {
  status: 'done' | 'blocked' | 'delegated';
  summary: string;
  tokens_in?: number;
  tokens_out?: number;
  model?: string;
  delegate_to?: string;        // 当status === 'delegated'时，填写目标Agent的ID
}

Multi-Company Setup

多公司搭建

typescript

// Create isolated companies in one deployment
const companies = await Promise.all([
  createCompany({ name: 'NoteGenius', mission: 'Best note app' }),
  createCompany({ name: 'ShipFast', mission: 'Fastest deploy tool' }),
]);

// Each company has its own agents, goals, tasks, budgets, and audit log
// No data leaks between companies

typescript

// 在一个部署中创建相互隔离的公司
const companies = await Promise.all([
  createCompany({ name: 'NoteGenius', mission: '最佳笔记应用' }),
  createCompany({ name: 'ShipFast', mission: '最快部署工具' }),
]);

// 每个公司都有独立的Agent、目标、任务、预算和审计日志
// 公司之间不会发生数据泄露

Governance & Approvals

治理与审批

typescript

// Fetch pending approval requests (you are the board)
const { approvals } = await fetch(
  `http://localhost:3100/api/v1/companies/${companyId}/approvals?status=pending`,
  { headers }
).then(r => r.json());

// Approve a hire
await fetch(`http://localhost:3100/api/v1/approvals/${approvals[0].id}`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({ decision: 'approved', note: 'Looks good.' }),
});

// Roll back a bad config change
await fetch(`http://localhost:3100/api/v1/agents/${agentId}/config/rollback`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ revision: 3 }),
});

typescript

// 获取待审批请求（你作为董事会）
const { approvals } = await fetch(
  `http://localhost:3100/api/v1/companies/${companyId}/approvals?status=pending`,
  { headers }
).then(r => r.json());

// 批准招聘请求
await fetch(`http://localhost:3100/api/v1/approvals/${approvals[0].id}`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({ decision: 'approved', note: '看起来不错。' }),
});

// 回滚错误的配置变更
await fetch(`http://localhost:3100/api/v1/agents/${agentId}/config/rollback`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ revision: 3 }),
});

Environment Variables Reference

环境变量参考

bash

undefined

bash

undefined

Required

必填

PAPERCLIP_API_KEY= # Your API key for the Paperclip server

PAPERCLIP_API_KEY= # Paperclip服务器的API密钥

Database (defaults to embedded Postgres in dev)

数据库（开发环境默认使用嵌入式Postgres）

DATABASE_URL= # postgresql://user:pass@host:5432/db

Storage (defaults to local filesystem in dev)

存储（开发环境默认使用本地文件系统）

STORAGE_DRIVER=local # 'local' | 's3' STORAGE_BUCKET= # S3 bucket name STORAGE_REGION= # AWS region AWS_ACCESS_KEY_ID= # From your environment AWS_SECRET_ACCESS_KEY= # From your environment

STORAGE_DRIVER=local # 'local' | 's3' STORAGE_BUCKET= # S3存储桶名称 STORAGE_REGION= # AWS区域 AWS_ACCESS_KEY_ID= # 从环境变量获取 AWS_SECRET_ACCESS_KEY= # 从环境变量获取

Server

服务器

PORT=3100 BASE_URL=http://localhost:3100

Agent-side (used inside agent processes)

Agent端（在Agent进程中使用）

PAPERCLIP_BASE_URL=http://localhost:3100 PAPERCLIP_AGENT_ID= # The agent's UUID from Paperclip

---

PAPERCLIP_BASE_URL=http://localhost:3100 PAPERCLIP_AGENT_ID= # Paperclip中Agent的UUID

---

Common Patterns

常见模式

Pattern: Manager delegates to reports

模式：经理向下属委派任务

typescript

// In your manager agent's heartbeat handler:
const { tasks } = await client.heartbeat(MANAGER_AGENT_ID);

for (const task of tasks) {
  if (task.complexity === 'high') {
    // Delegate down the org chart
    await fetch(`http://localhost:3100/api/v1/tasks/${task.id}/delegate`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ to_agent_id: engineerAgentId }),
    });
  }
}

typescript

// 在经理Agent的心跳处理逻辑中：
const { tasks } = await client.heartbeat(MANAGER_AGENT_ID);

for (const task of tasks) {
  if (task.complexity === 'high') {
    // 向下属委派任务
    await fetch(`http://localhost:3100/api/v1/tasks/${task.id}/delegate`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ to_agent_id: engineerAgentId }),
    });
  }
}

Pattern: @-mention an agent in a task thread

模式：在任务线程中@提及Agent

typescript

await fetch(`http://localhost:3100/api/v1/tasks/${taskId}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    role: 'human',
    content: `@${designerAgentId} Can you review the UI for this feature?`,
  }),
});
// Paperclip delivers the mention as a trigger to the designer agent's next heartbeat

typescript

await fetch(`http://localhost:3100/api/v1/tasks/${taskId}/messages`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    role: 'human',
    content: `@${designerAgentId} 你能审核这个功能的UI吗？`,
  }),
});
// Paperclip会在设计师Agent的下一次心跳时推送该提及通知

Pattern: Export a company template (Clipmart)

模式：导出公司模板（Clipmart）

typescript

const blob = await fetch(
  `http://localhost:3100/api/v1/companies/${companyId}/export`,
  { headers }
).then(r => r.blob());

// Saves a .paperclip bundle with secrets scrubbed
fs.writeFileSync('my-saas-company.paperclip', Buffer.from(await blob.arrayBuffer()));

typescript

const blob = await fetch(
  `http://localhost:3100/api/v1/companies/${companyId}/export`,
  { headers }
).then(r => r.blob());

// 保存一个清除了敏感信息的.paperclip包
fs.writeFileSync('my-saas-company.paperclip', Buffer.from(await blob.arrayBuffer()));

Pattern: Import a company template

模式：导入公司模板

typescript

const form = new FormData();
form.append('file', fs.createReadStream('my-saas-company.paperclip'));

await fetch('http://localhost:3100/api/v1/companies/import', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.PAPERCLIP_API_KEY}` },
  body: form,
});

typescript

const form = new FormData();
form.append('file', fs.createReadStream('my-saas-company.paperclip'));

await fetch('http://localhost:3100/api/v1/companies/import', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.PAPERCLIP_API_KEY}` },
  body: form,
});

Troubleshooting

故障排除

Problem	Fix
`ECONNREFUSED localhost:3100`	Server not running. Run `pnpm dev` first.
`401 Unauthorized`	Check `PAPERCLIP_API_KEY` is set and matches server config.
Agent never wakes up	Verify `heartbeat.enabled: true` and cron expression is valid. Check server logs for scheduler errors.
Budget exhausted immediately	`monthly_usd` budget too low or tokens_in/tokens_out are being over-reported. Check `POST /agents/:id/cost` payloads.
Task stuck in `open`	Agent may be offline or heartbeat misconfigured. Check `/api/v1/agents/:id/status` .
Database migration errors	Run `pnpm db:migrate` after pulling new commits.
Embedded Postgres won't start	Port 5433 may be in use. Set `EMBEDDED_PG_PORT=5434` in `.env` .
Org chart not resolving	`reports_to` agent ID must exist before creating the subordinate. Create top-down.

问题	解决方法
`ECONNREFUSED localhost:3100`	服务器未运行。先执行 `pnpm dev` 启动服务器。
`401 Unauthorized`	检查 `PAPERCLIP_API_KEY` 是否已设置，且与服务器配置一致。
Agent始终不唤醒	验证 `heartbeat.enabled: true` 且cron表达式有效。检查服务器日志中的调度器错误。
预算立即耗尽	`monthly_usd` 预算设置过低，或tokens_in/tokens_out上报数据过高。检查 `POST /agents/:id/cost` 的请求体。
任务一直处于 `open` 状态	Agent可能离线或心跳配置错误。检查 `/api/v1/agents/:id/status` 。
数据库迁移错误	拉取新提交后执行 `pnpm db:migrate` 。
嵌入式Postgres无法启动	端口5433可能被占用。在 `.env` 中设置 `EMBEDDED_PG_PORT=5434` 。
组织架构图无法解析	创建下属Agent前， `reports_to` 指定的上级Agent必须已存在。应自上而下创建。

Resources

资源

Docs: https://paperclip.ing/docs
GitHub: https://github.com/paperclipai/paperclip
Discord: https://discord.gg/m4HZY7xNG3
Clipmart (company templates): https://paperclip.ing/clipmart (coming soon)

文档： https://paperclip.ing/docs
GitHub： https://github.com/paperclipai/paperclip
Discord： https://discord.gg/m4HZY7xNG3
Clipmart（公司模板库）： https://paperclip.ing/clipmart （即将推出）