Paperclipが何を解決するかと、内部でどう動くかは前回までの記事で解説しました。今回は実際にインストールします。空のターミナルからCEOエージェントが最初のハートビートを実行するまで、7ステップ、15分で完了します。
各ステップには2つの方法があります。UI（初めての方向け）とCLI（慣れた方や自動化が必要な場合向け）です。どちらを選んでも結果は同じです。
必要な環境 — 準備するのは3つだけ
始める前に、以下の3点を確認してください。
- Node.js 20以上 —
node --versionで確認できます。未インストールまたは古いバージョンの場合は、nvm経由でインストール:nvm install 20 - pnpm 9.15以上 — Paperclipが使用するパッケージマネージャーです。インストール:
npm install -g pnpm。確認:pnpm --version - AnthropicのAPIキー — Paperclipではエージェントの実行にLLMアダプターが必要です。本記事ではClaude（Anthropic）を例に進めます。GPT-4、Gemini、ローカルモデルも利用可能ですが、現時点ではClaudeがPaperclipとの相性で最も安定した結果を出しています。
以上です。Dockerは不要です。PostgreSQLの個別インストールも不要です。AWSなどのクラウドアカウントも不要です。Paperclipは組み込みデータベースとストレージをマシン上で自動管理します。
Node.jsとターミナルがあれば、あと必要なのはnpm install -g pnpmの1コマンドだけです。
Paperclipのインストール — クローン、インストール、起動
2つのインストール方法があります。状況に合わせて選んでください。
方法1 — 最速（1コマンド、クローン不要）：
npx paperclipai onboard --yes
Paperclip CLIをダウンロードし、デフォルト設定（組み込みPostgreSQL、ポート3100、認証なし）でオンボーディングウィザードを実行し、サーバーを自動起動します。完了です。
方法2 — リポジトリをクローン（ソースコードを確認したい場合に推奨）：
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm installが完了したら（ネットワーク環境にもよりますが1〜2分程度）、サーバーを起動します。
pnpm dev
pnpm devはAPIサーバーとUIをdevelopmentモード（ウォッチモード）で起動します。組み込みPostgreSQLは自動的に作成されます。データベースの個別セットアップは不要です。
各コンポーネントを個別に制御したい場合（外部PostgreSQL、ポート変更、S3ストレージなど）は、~/.paperclip/instances/default/config.jsonを直接編集するか、pnpm paperclipai onboardを再実行してください。初回はデフォルトで十分です。
Paperclipは~/.paperclip/instances/default/フォルダを作成し、必要なものをすべて格納します。
config.json— サーバー、データベース、ストレージの設定db/— 組み込みPostgreSQLのデータ。PostgreSQLを別途インストールする必要はありません。Paperclipにバンドルされています。secrets/master.key— APIキーと認証情報の暗号化キーlogs/— サーバーログ
ターミナルにListening on http://127.0.0.1:3100と表示されたら、サーバーは起動完了です。ブラウザでhttp://localhost:3100を開いてください。
注目すべき点が1つあります。この段階ではすべてのデータがお使いのマシン上に保存されています。クラウドサービスへの通信は発生しません。サーバーはローカルで動作し、データベースもローカル、UIも同じプロセスから配信されます。エージェントがLLM APIを呼び出すとき以外は、Paperclipを完全にオフラインで運用できます。
ポート3100がすでに使用されている場合、Paperclipはエラーを返します。記事末尾のトラブルシューティングを参照してください。
オンボーディングウィザード — UIでカンパニー、エージェント、最初のタスクを作成
http://localhost:3100を初めて開くと、空のダッシュボードではなく、オンボーディングウィザードが表示されます。4つのステップでカンパニーの作成、最初のエージェントの作成、タスクの割り当てまでガイドされます。これが最も簡単な開始方法です。
ステップ1 — カンパニーに名前を付ける
ウィザードがカンパニー名の入力を求めます。「My AI Team」やプロジェクト名で構いません。
Paperclipにおけるカンパニー（Company）は、完全に隔離されたワークスペースです。各カンパニーは独自のエージェント、タスク、予算、監査証跡を持ちます。カンパニーAのエージェントはカンパニーBの存在を知りません。同じオフィスビルに入居する2つの別会社のようなものです。
実運用では、多くのチームが1プロジェクトにつき1カンパニーを割り当てています。「ECバックエンド」「モバイルアプリ」「データパイプライン」といった形です。データ、予算、アクセス権限がそれぞれ分離されます。プロジェクトAのエージェントがプロジェクトBのコードを誤って読むことは絶対にありません。PaperclipがAPI境界で自動的に制御します。
ステップ2 — 最初のエージェントを作成
ウィザードがエージェント作成画面に切り替わります。名前を入力し（例: 「CEO」）、モデルを選択します（Claude Opus、Claude Sonnet、GPTなど）。Claude CodeとCodexが推奨アダプターとして表示され、その他のタイプは下に折りたたまれています。ウィザードはアダプター環境を自動チェックし、成功時は緑色のアニメーション、失敗時はデバッグ出力が表示されます。
Nextをクリックして続行します。
アダプター（Adapter）とは何か。前回の記事で、Paperclipはコントロールプレーン（Control Plane）であると解説しました。指揮はするが、実行はしない。アダプターが「実行部隊」です。LLMが実際に動作するランタイムです。claude_localはお使いのマシン上でAnthropic API経由でClaudeを呼び出します。Paperclipは他にもcodex_local（OpenAI Codex）、cursor（Cursor IDE）、gemini_local（Google Gemini、v0.3.1以降）、openclaw_gateway（OpenClaw）、カスタムHTTPアダプター（任意のモデル対応）をサポートしています。
ステップ3 — CEOに最初のタスクを割り当て
ウィザードがタスク入力フォームを表示します。デフォルトのプレースホルダーテキストがあり、CEOに自身のメタデータファイル（AGENTS.md、SOUL.md、HEARTBEAT.md、TOOLS.md）の作成を依頼する内容です。デフォルトを使用するか、別のタスクを入力できます。
ステップ4 — イシューを公開
Publish（またはCreate Issue）をクリックしてCEOにタスクを割り当てます。タスクが作成され、エージェントにアサインされます。
公開後、Paperclipは自動的にCEOのハートビートをトリガーします。エージェントが起動し、タスクを読み、作業を開始します。ダッシュボードとインボックスで進捗を追跡できます。
CEOが最初のタスクを完了すると、インボックスにリプライが表示されます。通常、CEOはエンジニアなどの追加エージェントの採用を提案し、あなた（ボード）の承認（Approval）を求めます。Approveをクリックして承認してください。
以上で完了です。UIでの4ステップ、ターミナルコマンドは一切不要です。
CLIで同じ手順を実行する方法（パワーユーザー向け）
UIではなくターミナルを使いたい場合、または自動化が必要な場合は、同じ手順をCLIで実行できます。
エージェントを作成：
pnpm paperclipai agent local-cli ceo --company-id <company-id>
claude_localアダプターを使用する「ceo」エージェントを作成します。ターミナルに環境変数ブロックが表示されます。コピー＆ペーストしてください。
export PAPERCLIP_API_URL='http://127.0.0.1:3100'
export PAPERCLIP_COMPANY_ID='<your-company-id>'
export PAPERCLIP_AGENT_ID='<your-agent-id>'
export PAPERCLIP_API_KEY='pcp_...'
local-cliコマンドはPaperclipスキル（Skills）を~/.claude/skills/にインストールします。スキルとは、Claude Codeが起動時に読む命令ファイルのセットです。ハートビートプロトコルの従い方、タスクのチェックアウト方法、結果コメントの投稿方法、問題発生時のエスカレーション方法をエージェントに教えます。スキルがなければ、エージェントは自分が「会社」の一員であることを知りません。スキルがあれば、自分の役割と従うべきプロセスを正確に理解します。
タスクを作成：
pnpm paperclipai issue create \
--company-id <company-id> \
--title "Create hello-world.md" \
--description "Create a hello-world.md file with a short project introduction." \
--status todo \
--assignee-agent-id <agent-id>
ハートビートを手動トリガー：
pnpm paperclipai heartbeat run --agent-id <agent-id>
ターミナルにリアルタイムでログが流れ始めます。エージェントが起動し、GET /api/agents/meでアイデンティティを確認、GET /api/agents/me/inbox-liteでタスクを確認、POST /api/issues/{id}/checkoutでタスクをクレームします。全体で30〜90秒ほどです。
本番環境では、ハートビートは自動で実行されます。インターバル方式またはイベント駆動方式です。ここでは手動トリガーで全プロセスを観察しています。
エージェント作成後の設定 — UIでのカスタマイズ
ウィザードまたはCLIでエージェントを作成した後、UIで設定を編集できます。カンパニーに移動し、エージェントを選択して設定ページを開きます。インターフェースはタブで構成されています。
Agent Settings: 名前の変更（例: 「CEO」から具体的な名前へ）、組織図に表示されるタイトルの設定、能力の記述（エージェントが何をできるか — 他のエージェントが委任先を判断する際に参照されます）。
Adapter: アダプタータイプの選択（Claude Code、Codex、Cursor、OpenCodeなど）、作業ディレクトリの設定（絶対パスを使用）、エージェント指示ファイルへのパス（AGENTS.mdのパス）。
Config: モデルの選択（Claude Opus、Sonnet、その他 — エージェントごとに異なるモデルを割り当ててコストを最適化できます）、思考モードの切り替え、Chromeブラウザアクセスの有効化。
Heartbeat: ハートビート間隔の設定 — エージェントがどのくらいの頻度で起動するか、自動ハートビートを有効にするか手動トリガーのみにするか。
初回は設定変更の必要はありません。デフォルトで十分に機能します。ただし、5〜10エージェントにスケールする際は、ここで各エージェントを役割に合わせて微調整します。
結果を確認 — ダッシュボード、監査証跡、コスト
UIに戻り、ダッシュボードを開きます。
タスクステータス: done — タスクが完了しています。タスクをクリックすると、コメントスレッド全体が確認できます。エージェントがいつチェックアウトし、何をし、何を生成したか。
コスト: 各ハートビートで実際のコストが記録されています。例: 「Run #1 — $0.85 — 45秒 — 1タスク完了」。1ドル単位でどこに費用が発生したかが分かります。月末に予想外の請求が来ることはありません。
監査証跡（Audit Trail）: すべてのアクションにランID（Run ID）（ハートビート実行の識別子）が紐づいています。エージェントが14:32:05にタスクをチェックアウトし、14:32:47にコメントを投稿し、14:32:48に完了マーク。誰が何を、いつ、いくらのコストで実行したか、完全にトレース可能です。10エージェントにスケールした際、この監査証跡が統制を維持する手段になります。痕跡を残さずに行動するエージェントは存在しません。
組織図（Org Chart）: Org Chartタブに移動すると、視覚的な階層構造を確認できます。誰が誰にレポートするか、一目で明確です。CEOが追加エージェントを採用すると（あなたの承認後）、組織図は自動的に更新されます。
通常のAIエージェント運用と比較してみてください。ターミナルを開き、Claude CodeやCursorを起動し、口頭やプロンプトで作業を指示し、完了後はトークン消費量も実行時間もステップの省略有無も分からない。Paperclipはその不透明なプロセスを完全に可視化します。
以上で完了です。1カンパニー、1エージェント、1件の完了タスク、完全な監査証跡、正確なコスト数値。すべて15分以内に構築できました。
トラブルシューティング — よくある5つの問題と対処法
1. ポート3100が使用中
エラー: EADDRINUSE: address already in use :::3100。対処: 既存プロセスを終了（Mac/Linux: lsof -i :3100、Windows: netstat -ano | findstr :3100）するか、~/.paperclip/instances/default/config.jsonのserver.portでポートを変更します。
2. Node.jsのバージョンが古い
エラー: 構文エラーまたはSyntaxError: Unexpected token。対処: node --versionで確認し、20以上が必要です。nvm install 20 && nvm use 20で素早くアップグレードできます。
3. 組み込みPostgreSQLが起動しない
エラー: Failed to start embedded postgres。主な原因: ~/.paperclip/ディレクトリに書き込み権限がない、または前回のインスタンスがまだ実行中。対処: pnpm paperclipai doctor --repair — ほとんどの問題を自動的に診断・修復します。
4. エージェントがタスクを取得しない
ハートビートは実行されるが、エージェントが「No work found.」と報告する。3点を確認してください。(a) タスクが正しいエージェントIDにアサインされているか (b) タスクのステータスがtodoか (c) 環境変数がソースされているか。確認: echo $PAPERCLIP_AGENT_ID
5. ハートビートがタイムアウトする
エージェントが開始するがタイムアウトで完了しない。原因: デフォルトのタイムアウトに対してタスクが複雑すぎる、またはLLM APIキーが期限切れ/無効。対処: エージェント設定でtimeoutSecを増やすか、Anthropicダッシュボードでキーを確認します。
汎用的なアドバイス: 問題が発生したら、まずpnpm paperclipai doctorを実行してください。データベース、設定、パーミッションをチェックし、修復可能なものは自動修復します。--repairフラグを追加すると、確認なしで自動的にフィックスを適用します。
上記5つの方法で解決しない場合は、~/.paperclip/instances/default/logs/のログを確認してください。ログファイルにはサーバーが行ったすべての処理が記録されており、ターミナル出力では明確に表示されないエラーも含まれています。
次回: 1エージェントから10エージェントへのスケーリング
1つのエージェントが稼働し、1つのタスクが完了し、インフラ全体が整いました。基盤は盤石です。
しかし、1エージェントは始まりにすぎません。2つ目、3つ目、10個目のエージェントを追加するとき、誰が誰にレポートするのか。誰がコードを承認する権限を持つのか。誰に予算の上限が設定されるのか。次回の記事では、AIチームのための組織図を設計します。階層構造から権限設定、指揮系統から予算配分まで。
