تفضل ترجمة الـ HTML إلى العربية:
複数のAIエージェントを運用しているほとんどの開発者が、エージェント5番で同じ障害にぶつかります。1つの端末ウィンドウではClaude Codeがバックエンドのサービスを書き換え、別のウィンドウではCodexがテストを生成し、Cursorはコンポーネントを編集します。そして、残り3つのタブはどれも確認するのを忘れていました。誰も他のものが何をしているのか分かりません。コストが膨らみます。作業は2つのエージェントによって繰り返されます。一方は6時間動いているのに、誰も明確な目的を与えていなかったため、役に立つ成果を何も出せません。
Paperclipがそれを解決します。これはオープンソースのオーケストレーション・プラットフォームで、散らばっているAIエージェントを「きちんとした会社」にまとめ上げます。組織図、明確な役割、タスク管理、予算上限、監査ログまで揃っています。3週間以内にGitHubで35,000以上のスターを獲得しており、同じフラストレーションに悩んでいた開発者がどれだけ多いかを物語っています。
この記事では、Paperclipのセットアップ方法、最初のエージェント会社の構成方法、そして、端末ウィンドウを逐一監視する必要なく実際に仕事を進める方法を説明します。
Paperclipとは何か（そして何ではないか）
インストールを始める前に、Paperclipが正確に何をするのか、そしてそれをあなたのワークフローにどう組み込めるのかを理解する必要があります。
Paperclip は、エージェントのためのオーケストレーション層です。エージェントを整理し、作業を追跡し、予算を制御し、会社の目標に関するコンテキストを提供します。Paperclipはエージェントを自分で構築しません。同じように、AI提供事業者の代替にはなりません。またチャットUIも追加しません。
- エージェントには明確な役割があり、単なるプロンプトではありません
- タスクには特定のオーナーが割り当てられています
- 予算には厳格な上限があります
- すべてが監査ログに記録されます
PaperclipはClaude Code、OpenAI Codex、Cursor、Gemini CLI、そしてWebhookまたはheartbeatをサポートする任意のエージェントに対応しています。エージェントを追加するのはあなたで、Paperclipが会社を運用します。
Paperclip ではないもの：
- チャットUI
- n8nやZapierのようなドラッグ＆ドロップ式のワークフロー作成
- エージェントを作るためのフレームワーク
- 単発のユースケース向け
もし、単一のエージェントをときどき使うだけなら、Paperclipは向いていません。複数のエージェントを継続的に運用しているなら、これは必須のツールです。
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>/ — 各エージェントの作業フォルダ
ローカルモードでは、Paperclipは認証としてlocal_trustedを使用するため、アカウント登録なしでコントロールパネルをすぐに利用できます。
動作確認：
paperclipai doctor
問題があれば自動で修復：
paperclipai doctor --repair
最初の会社を設定する
「会社」とは、エージェント、タスク、目標、予算をまとめるメインのコンテナです。コントロールパネルから新しい会社を作成し、明確なミッションステートメントを追加してください。このステートメントは、すべてのタスクの参照先であり、エージェントへのコンテキストの源になります。
ミッションステートメントの例：
"REST APIを構築し、顧客のリクエストを管理するために保守する。速度よりも健全性を優先する。すべての公開エンドポイントを文書化する。"
最初のエージェントを追加する
Paperclipの各エージェントには、利用するAIツールと接続方法を定義するアダプタ（adapter）が必要です。
| エージェント | アダプタの種類 | パッケージ |
|---|---|---|
| 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 |
置換に{{variable}}を使うシステムプロンプト
|
maxTurnsPerRun |
1バーストあたりの最大ターン数（デフォルト：300） |
timeoutSec |
実行の最大継続時間（0 = タイムアウトなし） |
役割に応じたモデルのカスタマイズ：Opusを各エージェントに使うのは非常に高コストです。戦略/管理系の役割にはSonnetを、ガイダンスやルーチン作業にはHaikuを使いましょう。具体例：
- CEO / コーディネーションの役割： Sonnet
- マネージャ： Haiku
- クリエイティブなエンジニア： Sonnet
- ルーチンのタスク： Haiku
この配分により、ルーチン作業のタスク品質に影響を与えずに、月額コストを40〜60%削減できます。
返却形式: {"translated": "翻訳されたHTML"}組織構造とエージェント
小さなソフトウェアプロジェクトの例としての構成：
最高経営責任者（CEO）（Sonnet）
├── 最高技術責任者（CTO）（Haiku）
│ ├── バックエンドエンジニア（Backend Engineer）（Sonnet）
│ ├── フロントエンドエンジニア（Frontend Engineer）（Sonnet）
│ └── 品質保証エンジニア（QA Engineer）（Haiku）
└── テクニカルライター（Technical Writer）（Haiku）
最高経営責任者はタスクを目標に分解し、最高技術責任者が配布し、エンジニアが実行し、QAがレビューし、ライターが文書化します。
各エージェントにはハートビート間隔（heartbeat interval）があり、どのタイミングでエージェントが起床してタスクを確認し実行するかを決めます。これにより不要なリソース消費を防ぎます。
推奨の間隔：
- プログラミングエージェント：10分（600秒）
- オンデマンドエージェント：1日1回（86,400秒）＋オンデマンドで起床可能
- 最小値：30秒（それ以下はリスクとコストが増えます）
ハートビート（Heartbeat）の動作
すべてのハートビートは、次の手順を踏みます：
GET /api/agents/meで本人確認- 保留中のレスポンスの処理
GET /api/companies/{companyId}/issuesからタスクを取得- 優先度の決定：進行中のタスク → 計画中のタスク → ブロックされているタスク
POST /api/issues/{issueId}/checkoutでタスクを引き受ける- タスクのコンテキストとコメントを読み取る
- 作業を実行する
- 状態とコメントを更新する
- 必要に応じてサブタスクを委任する
引き受けの仕組みにより、複数のエージェント間で作業が重複して行われるのを防ぎます。コンテキストは環境変数経由でエージェントに渡されます：
PAPERCLIP_TASK_ID # タスク番号
PAPERCLIP_WAKE_REASON # 起床理由（一時、シグナル、割り当て）
PAPERCLIP_AGENT_ID # エージェントのID
PAPERCLIP_API_URL # APIのURL
エージェントは、同じハートビートの中で状態を更新したり、サブタスクを作成したり、承認を要求したり、委任したりできます。
タスクを割り当てて作業を追跡する
CLIまたはダッシュボードからタスクを作成します：
paperclipai issue create \
--company-id <id> \
--title "Add pagination to the orders endpoint" \
--assignee-agent-id <backend-engineer-id>
タスクは次をサポートします：
- メインタスクとサブタスク
- 目標へのリンク
- コメント、コンテキスト、承認依頼
- @シグナルによる、特定のエージェントを即座に起床
オープン中のタスクを表示するには：
paperclipai issue list
実際に機能する予算管理
各エージェントには月次予算があります。消費が80%に達したら、クリティカルなタスクにのみ集中します。100%になれば完全に停止します。
予算はエージェントの設定から割り当てられます（開始の目安として20〜50ドル/月）。消費量と、各ハートビートあたりのコストはダッシュボードで追跡できます。コストが増加しているのに気づいたら、まずタスクの明確さを確認してください。
Paperclipは過剰な消費を自動的に止めます。
ランタイムスキル：再トレーニングなしで新しいワークフローをエージェントに教える
Paperclipは、各エージェントのスキルフォルダ内のファイルSKILL.mdを介してスキル注入をサポートしています。ハートビートを実行すると、エージェントはこれらのファイルを読み込み、再トレーニングなしで従います。
# SKILL: Database migrations When creating a migration: 1. Never modify existing migration files 2. Use descriptive names: YYYYMMDD_description.sql 3. Include both up and down SQL 4. Test locally before committing 5. Add a comment explaining the business reason for the change
該当するエージェントのスキルフォルダにこのファイルを置けば、次回以降のすべてのハートビートでルールが自動的に適用されます。
あなたのエージェントが作成したAPIをテストする場合
エージェントがAPI（Application Programming Interfaces）を構築したら、素早くテストする必要があります。Apidogは、APIの設計とテストを行うための単一のプラットフォームを提供し、モック、オートテスト、更新後に出力を直接テストすることもサポートします。
OpenAPI仕様から自動的にテストセットを作成し、エージェントの結果に対して実行し、結果をタスクのコメントとして返せます。エージェントは次のハートビートでそれを受け取り、必要な修正を行います。コード→テスト→修正までをクローズドループで、人手なしで回せます。
ApidogはREST、GraphQL、gRPCをサポートし、無料で開始できます。
複数のインスタンスを管理する
Paperclipは、PAPERCLIP_INSTANCE_IDの変数、または各コマンドの--instanceにより、同一マシン上で隔離された複数のインスタンスを実行することをサポートします。各インスタンスには独自の設定、データベース、分離されたワークスペースがあります。
gitの各ブランチごとに新しい開発インスタンスを作成するには：
paperclipai worktree:make feature/orders-pagination
ポート、設定、データベースは各ブランチで分離されます。完了したら、インスタンスを簡単に削除できます。
複数のエージェントの効果的な設定
- 目標の分解順序：まずメインの目標から始め、そこをエージェントに目標とサブタスクへ分割させます。
- 承認ゲート：重要な操作には、必ず手動の承認ゲートを追加します。
- オンデマンドでの起床：ハートビート間隔を下げる代わりに、コメント内で@シグナルを使ってエージェントを即座に起こします。
- 隔離されたワークスペース：エージェントごとに別のワークフォルダを使い、作業の干渉を避けます。
開始には約15分かかります
初期セットアップは15分未満です。サーバーのインストールは1つのコマンド、最初のエージェント追加と最初のタスク作成には5分です。成果の大きな差は、会社の構造化、各ロールに適したモデルの選択、そして明確な予算設定によって生まれます。計画に30分投資すれば、生産性と持続性が大幅に高まります。
進行中のプロジェクトで2つ以上のAIエージェントを運用しているなら、Paperclipには初期設定のための午後の時間を確保する価値があります。エンドポイントのウィンドウが散らかっているだけの状態と、予算管理や監査ログによる統制ができる明確な組織構造の違いは、ちょっとしたお遊びで終わる企画か、常時の監督なしでも実際に機能し続けられる仕組みかの違いです。
