OpenClawのACPプロトコル活用｜外部エージェント連携ガイド

OpenClawの魅力の一つは、外部のAIエージェントと連携してタスクを遂行できる点です。この連携を実現するのが**ACP（Agent Communication Protocol）**です。ACPを活用すれば、OpenClawのセッション内からClaude Code、Codex CLI、Geminiなどの外部エージェントをspawnし、複雑なタスクを分散処理できます。

本記事は「OpenClaw 完全攻略」シリーズ第14回として、ACPプロトコルの基本概念からセットアップ、実践的な連携パターンまでを解説します。

OpenClaw ACPプロトコルのインフォグラフィック

ACPプロトコルとは？OpenClawにおける位置づけ

ACPは、OpenClawが外部のAIコーディングエージェントと通信するための標準プロトコルです。OpenClaw内蔵のサブエージェント機能（runtime="subagent"）とは異なり、ACPは独立したプロセスとしてエージェントを起動し、標準入出力またはAPIを介して通信します。

サブエージェント vs ACP の違い

項目	サブエージェント（subagent）	ACP
実行環境	OpenClawプロセス内	独立プロセス
使用モデル	OpenClawの設定モデル	エージェント固有のモデル
コンテキスト	OpenClawセッション共有	完全分離
適用場面	軽量タスク、クイック質問	コーディング、長時間タスク
セキュリティ	OpenClawのポリシーに従う	harness経由で制御

ACPの最大の利点は、各エージェントが得意なモデルとツールセットを使えることです。例えば、Claude Codeはファイル操作と推論に強く、Codex CLIはコード生成の速度に優れています。ACPで連携させることで、それぞれの長所を活かした最適な分業が可能になります。

OpenClawの基本についてはOpenClaw AIアシスタントガイドをご参照ください。

ACP対応エージェントのセットアップ

acp.allowedAgentsの設定

OpenClawの設定ファイル（openclaw.json）で、ACPで利用可能なエージェントを定義します。

{
  "acp": {
    "allowedAgents": [
      {
        "id": "claude-code",
        "command": ["claude", "--print"],
        "description": "Claude Code for complex coding tasks"
      },
      {
        "id": "codex-cli",
        "command": ["codex", "--quiet"],
        "description": "OpenAI Codex CLI for code generation"
      },
      {
        "id": "gemini-cli",
        "command": ["gemini"],
        "description": "Google Gemini CLI for analysis"
      }
    ]
  }
}

設定のポイント:

id: spawnする際に指定する識別子
command: エージェントを起動するコマンド（パスが通っている必要あり）
description: エージェントの用途の説明（OpenClawが最適なエージェントを選択する際に参照）

runtime=“acp”でのspawn方法

OpenClawのセッション内から、ACPエージェントをspawnする基本構文です。

sessions_spawn(
  runtime: "acp",
  agentId: "claude-code",
  task: "src/auth/のリファクタリングを実施して",
  mode: "run"
)

mode: "run": タスク完了後に自動終了（ワンショット）
mode: "session": 永続セッションとして維持（対話的なやりとりが可能）

外部エージェントとの通信フロー

ACPの通信フローを理解すると、トラブルシューティングが容易になります。

基本的な通信フロー

OpenClaw Session
  │
  ├─ spawn(agentId="claude-code", task="...")
  │     │
  │     ▼
  │  ACP Harness
  │     │  ← プロセス起動・環境設定
  │     ▼
  │  Claude Code (独立プロセス)
  │     │  ← タスク実行
  │     │  ← ファイル読み書き
  │     │  ← コマンド実行
  │     ▼
  │  完了通知
  │     │
  ▼
  結果受信・セッション継続

Harnessの役割

ACPのHarness（ハーネス）は、OpenClawとエージェントの間に立つ仲介レイヤーです。

環境の準備: 作業ディレクトリの設定、環境変数の注入
権限の制御: ファイルアクセス範囲、コマンド実行権限の制限
出力のキャプチャ: エージェントの標準出力・エラー出力を記録
タイムアウト管理: 長時間実行タスクの監視と強制終了

セキュリティとアクセス制御のベストプラクティス

ACPで外部エージェントを利用する際、セキュリティは最も重要な考慮事項です。

最小権限の原則

エージェントに与える権限は必要最小限に制限しましょう。

{
  "acp": {
    "allowedAgents": [
      {
        "id": "claude-code",
        "command": ["claude", "--print"],
        "permissions": {
          "fileAccess": ["src/", "tests/"],
          "commands": ["npm test", "npm run build"],
          "network": false
        }
      }
    ]
  }
}

機密情報の保護

環境変数: APIキーやトークンはACPエージェントに自動的には渡されない。必要な場合は明示的に設定
ファイルアクセス: .envや秘密鍵ファイルへのアクセスは制限する
ネットワーク: 不要なネットワークアクセスは禁止する

監査ログの活用

ACPの通信ログはOpenClawのセッションログに記録されます。定期的にレビューし、予期しない操作がないか確認しましょう。

セッション・サブエージェントの詳細はOpenClawセッション・サブエージェントガイドを参照してください。

実践例：Claude Code × OpenClaw × Codex CLIの連携

実際のプロジェクトでACPを活用した連携例を紹介します。

ユースケース: 新機能の実装からデプロイまで

# Step 1: Claude Codeで設計と実装
sessions_spawn(
  runtime: "acp",
  agentId: "claude-code",
  task: "ユーザー認証機能をOAuth2.0で実装して。
        設計書をdocs/auth-design.mdに作成し、
        src/auth/以下にコードを実装して"
)

# Step 2: Codex CLIでテスト生成
sessions_spawn(
  runtime: "acp",
  agentId: "codex-cli",
  task: "src/auth/以下の全ファイルに対する
        ユニットテストをtests/auth/に生成して"
)

# Step 3: OpenClaw自身でCI/CDトリガー
exec("npm test && npm run build")

ユースケース: レガシーコードのリファクタリング

# 分析フェーズ（Gemini CLIで広範な分析）
sessions_spawn(
  runtime: "acp",
  agentId: "gemini-cli",
  task: "src/legacy/ディレクトリのコード品質を分析し、
        リファクタリング優先度リストを作成して"
)

# 実装フェーズ（Claude Codeで段階的リファクタリング）
sessions_spawn(
  runtime: "acp",
  agentId: "claude-code",
  task: "分析結果に基づいて、優先度の高い3モジュールを
        リファクタリングして"
)

マルチエージェント設計の詳細はOpenClawマルチエージェント設計ガイドをご覧ください。

トラブルシューティングとデバッグ

よくある問題と対処法

1. エージェントが起動しない

# コマンドが正しくインストールされているか確認
which claude
which codex
which gemini

# パスが通っているか確認
echo $PATH

2. タイムアウトエラー

デフォルトのタイムアウトは10分です。大規模タスクの場合は延長しましょう。

sessions_spawn(
  runtime: "acp",
  agentId: "claude-code",
  task: "大規模リファクタリング",
  runTimeoutSeconds: 3600  # 1時間
)

3. 権限エラー

エージェントがアクセスしようとしたファイルやコマンドが許可リストにない場合に発生します。openclaw.jsonのpermissions設定を確認してください。

4. コンテキスト不足

ACPエージェントはOpenClawのセッションコンテキストを引き継ぎません。タスクの説明に十分な背景情報を含めることが重要です。

スキル開発についてはOpenClawスキル開発ガイドも参考にしてください。

まとめ

OpenClawのACPプロトコルは、AIエージェント間の連携を実現する強力なインフラです。

**ACPはruntime=“acp”**でspawnし、外部エージェントを独立プロセスとして実行
acp.allowedAgentsで利用可能なエージェントを定義し、セキュリティを担保
Harnessが環境設定・権限制御・タイムアウト管理を担当
最小権限の原則を守り、機密情報の保護を徹底
Claude Code × Codex CLI × Geminiの組み合わせで、設計・実装・テストを分業化

ACPを使いこなすことで、OpenClawは単なるAIアシスタントからマルチエージェントオーケストレーターへと進化します。まずは簡単なタスクからACPを試してみてください。

SES BASEでは、OpenClawをはじめとするAIツール活用術を発信中。 SES BASEで最新のシリーズ記事をチェック！

出典: OpenClaw「ACP Documentation」