Paperclip Multi-Agent Workflow完全ガイド

Paperclip Multi-Agent Workflowは、Agentが1〜2個の短時間作業なら導入せず、タスク、予算、承認、持続状態が崩れ始めた時点で採用するのが適切です。今週は、まず管理対象のAgent、必要なSecret、承認が必要な操作を一覧化し、個人利用かチーム運用かを判定してください。

最終更新日：2026年8月14日。情報は、Paperclip公式リポジトリのREADME、アダプター資料、Docker資料、認証資料、Secret管理資料、リリース履歴を確認しています。今後もアダプター、認証方式、データ保存方式に変更がないか更新時に再確認してください。

対象チームの切り分け

この記事は、次の読者を対象にしています。

• Claude Code、Codex、自作Agentを同時に管理する開発チーム
• タスク承認、予算制限、実行履歴を必要とする責任者
• Multi-Agent Workflow基盤を自社サーバーやMacで運用したい開発者

単発のコード修正や短い調査だけなら、ターミナル、GitHubのIssue、一般的なタスクボードのほうが速い場合があります。Paperclipは便利なチャットボットではなく、Agentを会社やチーム単位で動かす管理基盤です。公式資料でも、タスクやコメントを中心にAgentへ仕事を渡す設計であり、チャットボットやコードレビュー専用ツールではないと説明されています。公式の製品方針

Paperclipの役割

Paperclipは、複数のAI Agentを組織、プロジェクト、タスク、実行履歴、予算、権限の単位で扱うオープンソースの制御プレーンです。Agentそのものを新しく作るフレームワークというより、すでに存在するAgentランタイムへ仕事を渡し、結果を記録し、次の処理を決める層と考えると理解しやすいです。

公式リポジトリはMITライセンスで公開されています。2026年5月25日の公式リリースでは、Modal向けサンドボックス連携が追加され、同年3月のリリースでは実行ポリシー、承認フロー、依存タスク、会社データのインポートとエクスポートなどが案内されています。公式リポジトリとリリース履歴

Paperclip開発プラットフォームは何をするものですか。
複数Agentへ仕事を割り当て、Agentの実行結果をタスクやスレッドに戻し、必要に応じて次の担当へ渡すための基盤です。Agentの推論品質やモデル料金を自動的に改善する製品ではありません。どのモデルを使うか、どの権限を与えるか、どの成果物を承認するかは、運用側で決める必要があります。

Agent連携の境界

Paperclipには、Claude Code向けのclaude_local、Codex向けのcodex_local、OpenCode、Cursor、Pi、HTTP、任意のシェルコマンドを扱うProcessなどのアダプターがあります。アダプターは、Agentランタイムの起動、標準出力の取得、利用量やコスト情報の解析、構造化された実行結果の返却を担当します。公式アダプター一覧

PaperclipはClaude CodeとCodexに対応していますか。
公式アダプター資料では、Claude CodeとCodexのローカル実行アダプターが掲載されています。ただし、対応していることは、どのOSでも同じ設定で動くことを意味しません。CLIのインストール場所、ログイン状態、作業ディレクトリ、実行ユーザー、Secretの渡し方まで確認してください。

ここで重要なのは、PaperclipがAgentを魔法のように統合するわけではない点です。アダプターが利用できても、Agent側のCLI認証が切れていれば実行できません。複数の端末で個別にログインしていた状態を、Paperclipの設定だけで安全な共有認証へ変換できるわけでもありません。

人数別の導入判断

個人開発者では、Agentの数よりも「同じ仕事を何度も継続するか」が判断材料になります。Agentが1〜2個で、作業が数時間以内に終わり、承認者も自分だけなら、Paperclipの導入と保守のほうが負担になる可能性があります。

一方、複数のコーディングAgentが同じリポジトリや関連プロジェクトを扱う場合、タスクとスレッドの持続性が効いてきます。ターミナルを閉じた後も、誰が何を担当し、どの依存タスクが残っているかを追跡しやすくなります。

導入しないほうがよい条件

• 作業の大半が単発で、実行履歴を後から見返さない
• Agentが同時に動くことがほとんどない
• APIキーやリポジトリ権限を渡す必要がない
• Agentの実行ホストを常時オンラインにできない
• 管理画面やデータベースのバックアップを保守できない

導入する条件

• Agentごとに担当、権限、作業領域を分けたい
• タスクが数日以上続き、途中状態を保持したい
• 実行前に人の承認を入れたい
• モデル利用量や実行回数を組織単位で確認したい
• AgentをローカルMac、専用サーバー、サンドボックスへ分散したい

予算と承認の扱い

Paperclipの予算や実行制限は、運用上の上限を管理するための仕組みです。モデル提供元から請求される料金と同じものではありません。Agentの実行を止める設定があっても、クラウド側の契約、別経路のAPI利用、外部サービスの料金まで自動的に相殺するわけではありません。

承認フローも同様です。レビュー担当者を決め、実行ポリシーを設定することで、タスクを段階的に進める設計はできます。しかし、承認者が内容を確認せずに通過させれば、管理機能があってもリスクは残ります。承認は安全装置であり、最終的な判断を代替する機能ではありません。

注意：Agentの予算表示と、モデル提供元の請求額は別に照合してください。Paperclip側の記録、プロバイダーの利用明細、社内の請求ルールを分けて管理する必要があります。

Dockerと自社運用

PaperclipはDockerで運用できますか。
公式リポジトリにはDocker実行例とComposeのクイックスタートがあり、PAPERCLIP_HOMEをボリュームへ割り当てて状態を保存する構成が示されています。公式Docker Compose設定

ただし、コンテナを起動できることと、Agentまで安定運用できることは別です。データベース、アップロード、ログ、作業領域、Secretのマスターキーを永続化し、バックアップ対象を明確にする必要があります。コンテナを削除しても必要なデータが残るか、停止と再起動で確認してください。

5段階の導入手順

1. 対象Agentを分けます。
   Claude Code、Codex、HTTP Agent、シェル処理を一覧にし、担当プロジェクトと必要な権限を書き出します。

2. 実行ホストを決めます。
   ローカルMacは試用や対話的な開発向けです。常時オンラインのサーバーは定期実行向けです。リポジトリ操作やCLI認証をMac側に置きたい場合は、Mac環境の選び方も確認してください。

3. Dockerの永続領域を作ります。
   PAPERCLIP_HOME、データベース、ログ、作業領域、Secretのマスターキーを同じ復旧計画に含めます。コンテナを削除しても必要なデータが残るか、停止と再起動で確認します。

4. 認証モードを選びます。
   ローカル信頼モードは閉じた開発環境向けです。共有環境では認証付き配置を優先し、Agentの実行JWT、長期APIキー、運用者セッションを分けて管理します。公式認証資料

5. Secretを最小権限で接続します。
   Agentごとに必要なAPIキー、GitHub権限、クラウド権限だけをバインドします。全Agentへ同じ管理者キーを渡す設計は避けます。

6. 承認なしのテストを分離します。
   読み取り専用のリポジトリ、検証用API、低権限のアカウントで実行し、ログ、失敗時の再試行、タスクの重複起動を確認します。

7. 復旧テストを行います。
   データベースバックアップだけでなく、ローカル暗号化Secretを使う場合はマスターキーも復元し、Agent設定とSecret参照が戻ることを確認します。

Secret管理の安全境界

PaperclipはSecretを保存時に暗号化し、実行直前にAgentプロセスの環境変数、SSHコマンド、サンドボックス、HTTPリクエストへ渡します。公式資料でも、Paperclipが保護できるのはAgentやワークロードへ引き渡すまでであり、プロセスに届いた後の完全な秘匿は保証できないと説明されています。公式Secret管理資料

つまり、Agentは受け取ったSecretをログ、トランスクリプト、生成ファイル、外部ツールへの送信に使える立場です。Paperclipの暗号化だけで漏洩を防げるわけではありません。短期トークン、権限分離、Secretのローテーション、ログの監視を組み合わせてください。

経験則：Secretを渡す前に「このAgentが侵害された場合、何を変更できるか」を書き出してください。答えが広すぎる場合は、Paperclipの設定より先にクラウドIAM、リポジトリ権限、実行ユーザーを狭めるべきです。

本番前の決定分岐

次の条件で判断すると、導入後の手戻りを抑えられます。

• Agentが1〜2個で、作業が短時間で終わるなら、Paperclipではなくターミナルや既存タスクボードへ戻します。
• Agentが複数あり、担当と実行状態を毎日追うなら、Paperclipを試します。
• 承認が必要な操作があるなら、認証付き配置と実行ポリシーを先に設計します。
• Secretを複数のAgentへ共有するなら、共通キーを配らず、Agent別のSecretバインドへ分解します。
• 実行ホストを常時オンラインにできないなら、定期実行を前提にせず、手動ディスパッチ中心で検証します。
• コード編集とCLI認証をMacへ集約したいなら、Macを実行ホストにします。
• 再起動、バックアップ、監視を担当できる人がいないなら、自社運用を急がず、まず小規模な検証環境に限定します。

自宅やオフィスのMacを常時稼働させるのが難しい場合は、日本向けMacレンタル環境のような選択肢と、サーバー運用の手間を比較してください。地域、接続経路、CLI認証、作業領域の保存方法を確認してから決めるのが安全です。

Macとサーバーの選択

PaperclipをローカルMacへ置くと、Claude CodeやCodexのCLI、開発ツール、ローカルの作業環境を近い場所で扱えます。反面、Macのスリープ、再起動、ネットワーク切断、利用者のログアウトが定期実行の障害になります。

一般的なサーバーは常時稼働、監視、バックアップを組みやすい一方、macOS専用ツールや既存のMacログイン環境をそのまま持ち込めない場合があります。PaperclipをDockerで動かすだけならサーバーでも可能ですが、Agentの実行基盤まで含めると、OS、CLI、権限、認証ホームの差が問題になります。

自前のMacを使い続ける場合は、電源管理、スリープ解除、再起動後のサービス復旧、ディスク暗号化、管理者権限を確認してください。短期の検証やチームの試用であれば、常時稼働できるMac環境を借りて、同じバックアップとSecret管理の手順を試すほうが、自宅端末だけで判断するより失敗条件を見つけやすいです。

現在の運用から移行する前に

ターミナルを複数開く方法は初期費用が小さく、すぐ始められます。しかし、担当Agent、途中状態、承認者、Secretの利用先が分散し、作業が長期化するほど確認コストが増えます。共有サーバーだけで運用すると、CLI環境や権限が混ざり、誰の認証でAgentが動いたか追いにくくなる点も問題です。

そのため、Paperclipの導入条件を満たすチームでは、まず短期の自動化検証をMac環境で行い、タスク、予算、承認、Secretの復旧手順まで確認するのが現実的です。常時稼働する実行環境が必要でも、自前Macのスリープや更新作業を避けたい場合は、VPSSparkのMacレンタルを比較対象に入れると、Paperclip本体では解決しない運用上の停止要因を切り分けやすくなります。詳細はVPSSparkのサービス概要から確認できます。