複数のAIエージェントを動かしている開発者の多くが、5体目のエージェントの後に同じ問題に直面します。Claude Codeが端末でバックエンドのサービスを書き換え、Codexが別の端末でテストを生成し、Cursorがコンポーネントを編集し、さらに忘れられた3つのタブが残ります。誰もほかの作業を監視しないため、コストは増え、タスクは重複し、エージェントは方向性のないまま何時間も走り続けます。
Paperclipはこの問題を解決します。分散したAIエージェントを、組織図、役割、タスク管理、予算上限、監査ログを備えた“構造化された会社”へと変えるオープンソースのオーケストレーション基盤です。3週間未満でGitHubに35,000以上のスターが付いていることから、多くの開発者がこの痛みを感じていたことが分かります。
このガイドでは、最初のエージェント企業のセットアップと構造化、そして各端末を監視する必要なく仕事が流れていくようにすべてを動かす方法を紹介します。
Paperclipとは（そしてPaperclipではないもの）
インストールする前に、製品を理解してください。
Paperclipはオーケストレーションの層です。エージェントを調整し、作業を追跡し、予算を制御し、会社の目的に関するコンテキストを提供します。エージェントを作成するものではなく、あなたのAIプロバイダを置き換えるものでもなく、チャットUIを追加するものでもありません。
- エージェントには役割がある（プロンプトだけではない）
- タスクには担当者がいる（開いた端末だけではない）
- 予算には厳格な上限がある
- すべてが監査ログに記録される
Claude Code、OpenAI Codex、Cursor、Gemini CLI、そしてWebhookまたはheartbeatを受け付ける任意のエージェントで動作します。エージェントはあなたが用意し、Paperclipがオーケストレーションします。
Paperclipではありません：
- チャットボットUI
- n8nやZapierのようなドラッグ＆ドロップのフロー構築
- エージェントをプログラミングするためのフレームワーク
- 1つのエージェントだけで使う用途に特化
たまに1つのAIエージェントだけを動かすなら、Paperclipは過剰です。3つ以上のエージェントがあるなら、それは欠けていたピースです。
Paperclipのインストール
前提条件：Node.js 20+、pnpm 9.15+。PaperclipにはPostgreSQLのデータベースが組み込まれており、追加設定は不要です。
まずは素早く：
npx paperclipai onboard --yes
CLIをダウンロードし、既定の設定と連携して、ポート3100でサーバーを起動します。ダッシュボードを開くにはhttp://127.0.0.1:3100にアクセスしてください。
コントリビュート／開発する場合：
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Dockerを使う：
docker compose -f docker-compose.quickstart.yml up --build
ディスク上に作成されるファイル：
~/.paperclip/instances/default/
config.json — サーバー／ストレージの設定
db/ — 内部PostgreSQLのデータ
secrets/master.key — 暗号化キー（自動生成）
logs/ — サーバーログ
data/storage/ — 添付ファイル
workspaces/<agent>/ — エージェントごとのワークスペース
ローカルモードでは、認証local_trusted（ログインなし、ユーザーは「Board」）を使用します。ダッシュボードはすぐ使える状態で、アカウント作成は不要です。
すべてうまく動いているか確認：
paperclipai doctor
問題があれば、次を使います：
paperclipai doctor --repair
最初の会社の設定
Paperclipの「会社」とは、エージェント、タスク、目的、予算のためのメインコンテナです。メンバーそれぞれが、役割を持ち、報告するAIエージェントである“プロジェクト”だと考えてください。
ダッシュボードで新しい会社を作成し、ミッションを設定します。これは、エージェントのすべてのタスクに対するコンテキストとして機能し、長時間の実行で適切な判断を下すために不可欠です。
ミッション例：
"顧客の注文を管理するためのREST APIを構築し、保守する。速度よりも修正（正しさ）を優先する。公開するすべてのエンドポイントをドキュメント化する。"
このミッションは、すでにエージェントの判断を導きます。
最初のエージェントを追加する
各エージェントは、どのAIを使い、どのように通信するかを定義するアダプタを使用します。
| エージェント | アダプタの種類 | パッケージ |
|---|---|---|
| Claude Code | claude_local |
@paperclipai/adapter-claude-local |
| OpenAI Codex | codex_local |
@paperclipai/adapter-codex-local |
| Gemini CLI | gemini_local |
@paperclipai/adapter-gemini-local |
| Cursor | cursor |
@paperclipai/adapter-cursor-local |
| HTTP webhooks | HTTPアダプタ | カスタムエンドポイント |
CLIからClaude Codeエージェントを追加するには：
paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>
これによりエージェントが初期化され、~/.claude/skillsにスキルがインストールされ、API認証情報が生成されます。エージェントは組織図に追加され、すぐにタスクを受け取れるようになります。
Claudeエージェントの主なオプション：
| 項目 | 役割 |
|---|---|
model |
Claudeモデル（例：claude-sonnet-4-6） |
cwd |
エージェントの作業ディレクトリ |
promptTemplate |
システムプロンプト（{{variáveis}}を含む）
|
maxTurnsPerRun |
1実行あたりの最大ターン数（既定：300） |
timeoutSec |
実行タイムアウト（0＝上限なし） |
役割ごとのモデル割り当て： すべてのエージェントでOpusを使わないでください。提案：
- CEO / オーケストレーション: Sonnet
- マネージャー: Haiku
- クリエイティブ/コードIC: Sonnet
- ボイラープレート/テストIC: Haiku
これにより、定型タスクにおいて実際の品質低下なしに、エージェントの月額コストを40〜60%削減します。
エージェント組織を構築する
ソフトウェアプロジェクトの例:
CEO (Sonnet)
├── CTO (Haiku)
│ ├── バックエンドエンジニア (Sonnet)
│ ├── フロントエンドエンジニア (Sonnet)
│ └── QAエンジニア (Haiku)
└── テクニカルライター (Haiku)
CEOはミッションを維持し、目標を配分します。CTOはエンジニアへ振り分けます。エンジニアが実行します。QAが検証します。テクニカルライターがドキュメント化します。
各エージェントにはパルス間隔（heartbeat）があります。つまり、起床する頻度、タスクを確認して実行し、そして眠るまでの周期です。これによりコストを制御できます。
推奨される間隔:
- コード: 600s（10分）
- 必要に応じて: 86400s（1回/日）＋必要時のオンデマンド起動
- 安全な最小値: 30s
パルス（heartbeat）はどのように機能するか
信頼性のために、パルスを理解してください:
GET /api/agents/meで身元を確認する- 保留中の承認を処理する
GET /api/companies/{companyId}/issuesでタスクを取得する- 優先順位付け: 進行中 > やること、ブロックされているものは無視する
POST /api/issues/{issueId}/checkoutを行う（他のエージェントによる実行をブロックする）- コンテキストとコメントを読む
- タスクを実行する
- ステータスとコメントを更新する
- 必要に応じてサブタスクを委譲する
チェックアウト（手順5）は作業の重複を防ぎます。各タスクを1度に掴むのは1つのエージェントだけです。
Paperclipは環境変数を通じてコンテキストを注入します:
PAPERCLIP_TASK_ID
PAPERCLIP_WAKE_REASON
PAPERCLIP_AGENT_ID
PAPERCLIP_API_URL
エージェントはこれらの変数を使ってAPIとやり取りしたり、サブタスクを作成したり、承認を求めたりします。
タスクを割り当てて作業を追跡する
タスクはGitHubのissue＋プロジェクト管理のように動きます。UIまたはCLIで作成してください:
paperclipai issue create \
--company-id <id> \
--title "受注エンドポイントにページネーションを追加する" \
--assignee-agent-id <backend-engineer-id>
タスクには以下が含まれます:
- サブタスク（親/子）
- 目標へのリンク
- コメント
- メンション（@）による即時起動
CLIで開いているタスクを見る:
paperclipai issue list
またはダッシュボードで、所有者・ステータス・実行履歴を確認します。
本当に機能する予算管理
各エージェントには月額トークンの予算が割り当てられます。80%に達したら、クリティカルなタスクだけを実行します。100%になったら停止します。
エージェント設定で予算を定義します。エージェントごとに月US$20〜50から始めてください。ダッシュボードには、エージェントごとの消費量、1パルスあたりのコスト、月間の総支出が表示されます。
あるエージェントの1パルスあたりのコストが上がった場合は、予算を増やす前に、プロンプトとタスクのスコープを調整してください。
管理なしだと、設定が不適切なエージェントがすぐに数百ドルを使い切ってしまう可能性があります。Paperclipはそれを防ぎます。
実行時スキル: 再トレーニングなしで新しいワークフローをエージェントに教える
Paperclipはスキル注入を可能にします。SKILL.mdのようなファイルを--add-dir経由でエージェントのコンテキストに追加します。エージェントはファイルを読み、定義されたフローに従います。
例: バックエンドエージェントにデータベース移行を教える:
# スキル: データベース移行
移行を作成するとき:
1. 既存の移行ファイルは決して変更しない
2. 説明的な名前を使う: AAAAAMMDD_descricao.sql
3. SQLの「up」と「down」を含める
4. コミットする前にローカルでテストする
5. 変更のビジネス上の理由を説明するコメントを追加する
エージェントのスキル用ディレクトリに保存すれば、以後の次のパルスから自動的にこのプロセスを実行します。
エージェントが構築したAPIをテストしている場合
エージェントがAPIを作成しているなら、素早いテストは不可欠です。Apidogを使いましょう。デザイン、モック、自動化されたAPIテストをすべて1か所で管理できます。エージェントがエンドポイントを納品したら、Swagger、Postmanなどを行き来せずに、すぐに検証してください。
OpenAPIのテストスイートを生成し、エージェントの出力で実行して、結果をタスクのコメントとして送り返します。エージェントは次のパルスでそれを回収し、自分で失敗を修正します。
ApidogはREST、GraphQL、gRPCに対応しており、始めるのは無料です。
複数インスタンスの管理
Paperclipは環境変数PAPERCLIP_INSTANCE_IDまたはフラグ--instanceを使って、分離された複数インスタンスをサポートします。それぞれに独自の設定、データベース、ポート、ワークスペースがあります。
ローカル開発では、gitのブランチごとに分離したインスタンスを作るためにworktreeを使ってください:
paperclipai worktree:make feature/orders-pagination
ブランチ用の別環境が手に入ります。完了したら削除すればよく、すべてクリーンになります。
機能するマルチエージェント設定
推奨パターン:
- 目標のカスケード: 上位からのトップダウンの目標を書き、CEOがプロジェクトへ分解し、マネージャーがタスクへ分解します。エージェントは連鎖の中で目的を理解します。
- 承認ゲート: 本番、請求などのクリティカルなアクションにはゲートを設定します。エージェントは停止して、手動での承認を待ちます。
- @メンションによるオンデマンド起動: パルス間隔は遅めに設定し、必要なときに@メンションでエージェントを即座に起動します。
- エージェントごとに分離されたワークスペース: 各エージェントにディレクトリを割り当てます。共有しないでください。干渉を避けます。
開始には約15分かかります
最初の統合：15分未満。インストールして、起動し、エージェントを追加して、ダッシュボード上で数分でタスクを作成できます。
重要なのは、会社を適切に構造化することです。明確なミッション、役割ごとの正しいモデル、予算の上限。タスクを配布する前にここに30分投資してください。エージェントの成果は、「とりあえず全部を急いでつなぐだけ」の場合よりもはるかに良くなります。
もし、すでに継続的なプロジェクトで2つ以上のAIエージェントを実行しているなら、設定のために午後の時間を確保する価値があります。各エージェントをターミナルで動かすのと、予算やログが整った構造化された企業にするのとでは、その差が生まれます。これが、横で並行して進めるだけのプロジェクトと、手動で監視しなくても機能するものを分けるのです。
