AIエージェントをソフトウェアチームに変える無料ツール「Paperclip」

複数のAIエージェントを動かしている開発者の多くは、5台目あたりで同じ課題に直面します。Claude Codeがバックエンドを書き換え、Codexがテストを生成し、Cursorがコンポーネント編集、他にも見落としがちなタブが複数……誰が何をしているのか分からず、コストも増大、作業は重複し、明確な目標がないエージェントは何も生み出さない。Paperclipはこの問題を解決するためのオープンソース・オーケストレーションプラットフォームです。AIエージェントを組織図・役割・タスク・予算・監査ログ付きの「会社」に変換でき、公開3週間で35,000以上のGitHubスターを獲得したのは、多くの開発者が同じ悩みを持っていた証拠です。この記事ではPaperclipのセットアップ方法、最初のエージェント会社の構築、そして全ターミナル監視不要で作業を進める具体的な手順を解説します。

Apidog を今すぐ試そう

Paperclipとは何か（そして何ではないか）

Paperclipはエージェントを調整し、作業進捗・予算管理・会社目標の文脈を与えるオーケストレーションレイヤーです。

• エージェント自体やAIプロバイダーの代替、チャットUI、ワークフロービルダーではありません。
• Claude Code/ OpenAI Codex / Cursor / Gemini CLI / Webhook/ハートビート対応なら何でも連携可（エージェントの用意は自分で）。

向いていない使い方

• チャットボットUI
• n8n, Zapierのようなワークフロービルダー
• エージェント作成フレームワーク
• 単一エージェント用途のみ

推奨ケース

3台以上のエージェント、継続的なAI作業のオーケストレーションが必要なとき。

Paperclipのインストール

要件: Node.js 20+、pnpm 9.15+

Paperclipは組み込みPostgreSQL付き。外部DB不要。

最速セットアップ

npx paperclipai onboard --yes

• CLIダウンロード・初期設定・サーバー起動まで自動化
• 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/               // データ
  secrets/master.key // 暗号化キー
  logs/             // ログ
  data/storage/     // 添付ファイル
  workspaces/       // エージェント作業ディレクトリ

ローカルモード

• デフォルトでlocal_trusted認証
• ログイン不要、合成ユーザーで即開始

ヘルスチェック

paperclipai doctor
# 問題あれば
paperclipai doctor --repair

最初の会社のセットアップ

Paperclipにおける「会社」は、エージェント・タスク・目標・予算のトップレベルコンテナです。

ダッシュボードから新規作成し、ミッションステートメント（例：REST API構築・維持、正確性重視、全エンドポイント文書化など）を入力します。

• これは装飾ではなく、タスク全体に会社ミッションの文脈が付与され、長期自律実行における意思決定のブレを防げます。

最初のエージェントの追加

Paperclipの各エージェントはアダプターで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 <ID>

• スキルは~/.claude/skillsにインストール、APIクレデンシャルも生成
• 組織図に追加され、タスク割当て可

Claudeエージェント設定項目
| フィールド | 機能 |
|------------------------|--------------------------------------------------|
| model | Claudeモデル例：claude-sonnet-4-6 |
| cwd | 作業ディレクトリ |
| promptTemplate | {{variable}}置換・システムプロンプト |
| maxTurnsPerRun | ハートビートごとの最大ターン数（デフォルト300） |
| timeoutSec | 実行タイムリミット（0=無制限） |

モデル割当て推奨例

• CEO/オーケストレーション: Sonnet（戦略推論・コスパ良）
• マネージャー: Haiku（ルーティング・委任）
• 創造的/コーディングIC: Sonnet（品質重視）
• 定型IC: Haiku（ボイラープレート生成など） → 全エージェントOpus運用より40-60%コスト削減

エージェント組織の構築

小規模プロジェクト向けの構成例:

CEO (Sonnet)
├── CTO (Haiku)
│   ├── バックエンドエンジニア (Sonnet)
│   ├── フロントエンドエンジニア (Sonnet)
│   └── QAエンジニア (Haiku)
└── テクニカルライター (Haiku)

• CEOがミッション→目標分解
• CTOが目標→エンジニアにルーティング
• 各エンジニアが作業、QAが検証、ライターが文書化

ハートビート間隔

エージェントは継続起動せず、一定間隔でタスク確認→作業→停止。これでコスト増大抑制。

• コーディングエージェント: 600秒（10分）
• オンデマンド: 86400秒（1日1回、Wake On Demand可）
• 最小安全間隔: 30秒（これ未満はコスト超過・スパムリスク）

ハートビートの仕組み

エージェントごとに9ステッププロトコルで動作。重複作業を防ぐため、タスクは“チェックアウト”制。

基本フロー

1. GET /api/agents/me 本人確認
2. 保留中承認コールバック処理
3. GET /api/companies/{companyId}/issuesでタスク取得
4. 進行中タスク→ToDo優先
5. POST /api/issues/{issueId}/checkoutでタスクチェックアウト（重複不可）
6. タスクコンテキスト・コメント取得
7. 作業実行
8. コメント・ステータス変更でタスク更新
9. 必要に応じサブタスク委任

環境変数でエージェントに文脈注入

PAPERCLIP_TASK_ID        # 実行トリガータスク
PAPERCLIP_WAKE_REASON    # 起動理由（タイマー/メンション等）
PAPERCLIP_AGENT_ID       # エージェントID
PAPERCLIP_API_URL        # Paperclip APIコールバックURL

タスクの割り当てと作業の追跡

PaperclipのタスクはGitHub Issue＋PJ管理ツール的。UI/CLIで作成・割当て。

タスク作成例

paperclipai issue create \
  --company-id <ID> \
  --title "注文エンドポイントにページネーションを追加" \
  --assignee-agent-id <AGENT_ID>

• サブタスク親子構造、目標リンク、コメント、@メンションによるオンデマンド起動可

未処理タスク一覧

paperclipai issue list

• ダッシュボードでも現在の担当/状態/直近ハートビート履歴表示

実際に機能する予算管理

予算管理はマルチエージェント運用の最重要ポイント。

• 各エージェントに月間トークン予算付与
• 80%到達で重要タスクのみに自動シフト
• 100%で完全一時停止

設定例:

コミュニティ推奨：エージェント層ごと月額20〜50ドル

ダッシュボードで消費率/ハートビート単価/月間累積費用を可視化

• コスト急増時はプロンプト曖昧・タスク過大が原因。予算増額でなく割当厳格化で対処。
• Extended Thinking有効・短間隔運用だと一晩で高額消費リスク→Paperclipは自動で防止

ランタイムスキル：再トレーニングなしでエージェントに新しいワークフローを教える

スキル注入機能で、エージェントに新しい手順やルールを即時伝達可能。

• SKILL.mdを作成し、構成ディレクトリに配置するだけ
• Markdownで「データベース移行」等の業務手順を明示→プロンプト書き換え・再デプロイ不要

例：スキル定義

# SKILL: データベース移行
移行を作成する際には：
1. 既存の移行ファイルは変更しない
2. 記述的な名前 YYYYMMDD_description.sql を使う
3. up/down両方SQL記載
4. コミット前にローカルテスト
5. 変更理由をコメントで説明

保存→バックエンドエージェント割当てで、次回以降ハートビートから反映。

エージェントによって構築されたAPIをテストする場合

自動生成APIのテストには Apidog が最適です。

• API設計・モックサーバー・自動テストを一元化
• エージェントがエンドポイント公開→Swagger, Postman, モックツール切替不要で即時検証

• OpenAPI仕様からテストスイート自動生成→エージェント出力に即実行→タスクコメントでフィードバック
• エージェントは次のハートビートで自動修正
• REST/GraphQL/gRPC対応・無料プランあり

複数のインスタンスの管理

PaperclipはPAPERCLIP_INSTANCE_ID環境変数または--instanceで、1台のマシン上で複数の独立インスタンスを運用できます。

• 各インスタンスは構成/DB/ポート/ワークスペース完全分離

開発ブランチごとに独立環境作成例

paperclipai worktree:make feature/orders-pagination

• ブランチ単位で独自ポート・設定・DBを用意し、本番設定に影響せずテストが可能
• 完了後は破棄するだけ

機能するマルチエージェント設定

基本パターン例

• 目標カスケード: 会社→CEO→マネージャ→エンジニアの順で目標/タスク分割
• 承認ゲート: 本番/課金操作は承認必須
• @-メンション起動: 高速ハートビート不要、大きなコスト節約
• ワークスペース分離: 各エージェントごとworkspaces/<agent_id>/配下で作業。共用は競合・破壊リスク

始めるまでにかかる時間は約15分

Paperclipの初回オンボーディングは15分以内。

• サーバー導入〜起動はコマンド1つ
• エージェント追加＋タスク作成もダッシュボードで5分程度

構造化設計のコツ

• 明確なミッション
• 役割に応じたモデル選択
• 妥当な予算設定
• 作業開始前に30分これらに集中すると、エージェント成果が明らかに向上

既に複数AIエージェントを動かしている場合、Paperclipの導入は午後の投資に十分見合います。

ターミナルタブ管理から、予算・タスク・監査ログ付きの構造化AI会社に移行し、監視不要の本格運用を始めましょう。