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

Dev.to / 2026/4/1

💬 オピニオンDeveloper Stack & InfrastructureTools & Practical UsageModels & Research

共有:

要点

Paperclipは、複数のAIエージェントの実行を「オーケストレーション」し、役割・タスク・予算・監査ログなどの文脈を与えることで、開発チーム内の混乱やコスト増を抑えるための無料のオープンソース基盤です。
既存のエージェント実装（Claude Code、OpenAI Codex、Cursor、Gemini CLI、Webhook/ハートビート等）を連携可能であり、チャットUIやワークフロービルダー、エージェント作成フレームワークそのものではありません。
使いどころとしては、「3台以上のエージェント」かつ「継続的なAI作業の継続管理」が必要な場合が推奨されます。
最速のセットアップは、`npx paperclipai onboard --yes`でCLIから自動的に初期化してサーバーを起動することで、ローカルのダッシュボード（`http://127.0.0.1:3100`）で確認できます。
PostgreSQLを内蔵し、ローカル用のディレクトリ構成（設定、暗号化キー、ログ、作業ディレクトリ等）も用意されるため、外部DB不要で導入しやすい設計です。

複数の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ステッププロトコルで動作。重複作業を防ぐため、タスクは“チェックアウト”制。

基本フロー

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

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

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会社に移行し、監視不要の本格運用を始めましょう。

Black Hat USA

AI Business

Black Hat Asia

AI Business

みずほ証券・ぴあが挑む全工程AI駆動、開発のボトルネックは下流から上流に

日経XTECH

「時系列基盤モデル」に世界が熱視線、ビッグテックや研究機関の参画続く