もし実際のインフラストラクチャ — Azure デプロイメント、Terraform プラン、ネットワークプロビジョニング — に対して AI エージェントを動かしたことがあるなら、壁にぶつかったことがあるはずです。エージェントが長時間実行される CLI コマンドを発火させると、メインループ全体が暗転します。応答も、ステータス更新も、キャンセルする手段もありません。そのネットワーク呼び出しが戻ってくるまで、ただの沈黙。あるいは戻ってこないか。

これは本番の AI エージェントワークフローにおける最大の信頼性問題であり、それが私が OpenClaw の中で Agent Client Protocol (ACP) を強く推している理由です。ACP が魔法のように遅い操作を速くするわけではありません。ACP がするのは、それらを切り離すことで、あなたのエージェントを道連れにできないようにすることです。

どう動くのか、そしてどう設定するのかを説明します。

ACP とは実際に何か

Agent Client Protocol は、コーディングエージェントを異なるクライアント — IDE、エディタ、オーケストレータ、その他 — 間で相互運用可能にするための標準です。中核では、JSON-RPC over stdio を使ってホストアプリケーションとコーディングエージェント間の通信を標準化します。ローカルエージェントはサブプロセスとして起動され、そのパイプを通じて応答を返します。

それがスペックレベルの説明です。我々にとって重要なのは: ACP は OpenClaw に、外部のコーディングハーネス — Claude Code、Codex、Gemini CLI — をメインのエージェントループ内でインラインに処理するのではなく、監視付きの子プロセスとして実行する手段を与えます。

OpenClaw は ACP を双方向で使います:

  1. OpenClaw 内の ACP セッション — acpx バックエンドプラグイン経由で外部ハーネスを実行します。OpenClaw がプロセスを監視し、ライフサイクルを管理し、事態が悪化すれば kill できます。
  2. OpenClaw ACP ブリッジ(openclaw acp) — stdio 経由で ACP を話す CLI コマンドで、IDE が OpenClaw Gateway セッションにプロンプトを転送できます。

この記事では、1つ目を扱います。

核心的な問題: エージェントループはシングルスレッド

本番で私がよく見る失敗モードです。OpenClaw のメインエージェントターンが長時間実行される Azure ネットワーク呼び出し — 例えば VNet ピアリングのプロビジョニングや Terraform apply の待機 — を直接起動します。そのエージェントループはシリアライズされています。一度に1つの操作。Azure API の応答を待っている間、エージェント全体が応答不能になります。

チャット応答なし。他の作業を確認する能力なし。キャンセルボタンなし。その API 呼び出しが10分間ハングすると、エージェントは10分間ハングします。永遠にハングしたら — そして Azure のネットワーク呼び出しは完全に永遠にハングし得ます — エージェントは永遠にハングします。

タイムアウトを増やせば解決、という誘惑があります。それは解決策ではなく、期限付きの祈りです。

ACP がどう解決するか

「ACP は OpenClaw のハングを防ぐ」と人が言うとき、意味しているのは: リスキーで遅く、失敗しやすい作業をインラインで処理するのではなく、OpenClaw が監視する外部ハーネスプロセスで実行する、ということです。

acpx バックエンドは作業を監視付きの子プロセスに生成します。ランタイムがトランスポート、キューイング、キャンセル、再接続を処理します。Claude Code が決して戻らない Azure 呼び出し待ちでスタックしたとしても、そのスタックした作業は別のプロセスに存在します。OpenClaw のメインループは応答可能なままです。以下が可能です:

  • キャンセル そのスタックしたセッション
  • クローズ して TTL リーパーにクリーンアップを任せる
  • 新規セッションを生成 して別のことをする
  • バックグラウンド作業が実行中でもエージェントとチャットを続ける

これは AI エージェントオーケストレーションに適用されたプロセス分離です。目新しいコンピュータサイエンスではありません — Web サーバーをワーカープロセスなしのシングルスレッドイベントループとして動かさないのと同じ理由です。しかし、ほとんどのエージェントフレームワークでは驚くほど欠けています。

設定方法

前提条件

Claude Code は別個にインストールされている必要があります。Windows では PowerShell インストールスクリプトを使い、Linux/macOS では curl を使います。初回実行時に認証を求められます — ACP に組み込む前にそれを済ませておいてください。

acpx プラグインのインストール

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true

すべてが正しく接続されているか確認:

/acp doctor

これはバックエンドのヘルスチェックを実行します。失敗する場合、大抵は Claude Code のインストール不足か認証の問題です。

ACP の設定

主要な設定フィールド:

openclaw config set acp.enabled true
openclaw config set acp.backend "acpx"
openclaw config set acp.defaultAgent "claude-code"
openclaw config set acp.maxConcurrentSessions 8

acp.allowedAgents で利用可能なハーネスを制限し、runtime.ttlMinutes で寿命を超えたセッションを自動刈り取りできます。

権限の処理(ここで噛まれます)

ACP セッションは非インタラクティブに実行されます — TTY がありません。つまりデフォルトの権限モデル(読み取りは承認、書き込みは失敗)は、ハーネスがファイル書き込みやコマンド実行を試みた瞬間に AcpRuntimeError を投げます。

permissionMode と nonInteractivePermissions をセキュリティ姿勢に合わせて設定する必要があります。インフラストラクチャ自動化では、通常は書き込みと実行の権限を有効にする必要があります。これについて意図的に行ってください — ACP セッションはサンドボックス内ではなく、ホストランタイム上で実行されます。

日常の使い方

スラッシュコマンド

運用者のワークフローはシンプルです:

  • /acp spawn — 新しい ACP セッションを開始
  • /acp status — 実行中のセッションを確認
  • /acp timeout <seconds> — セッションタイムアウトを設定
  • /acp steer — 実行中のセッションに追加指示を送信
  • /acp cancel — スタックしたセッションを kill
  • /acp close — クリーンシャットダウン

プログラマティックな生成

自動化ワークフローでは、sessions_spawn を runtime: "acp" で使います。agentId パラメータが使用するハーネスを選び、mode は run(ワンショット、実行して返す)か session(永続的、フォローアップ作業のためにハーネスを維持)のいずれかにできます。

スレッドバインディングも機能します — Discord スレッドや Telegram フォーラムトピックを特定の ACP セッションに紐付けでき、チームがタスクごとに隔離された会話コンテキストを得られます。

ノンブロッキングパターン

ACP セッションはより広いツールキットの中の1つのツールです。エージェントワークフローを応答可能に保つために私が使う4つのパターンです:

オプション A: Exec のバックグラウンド化。 exec ツールは timeout パラメータ(デフォルト1800秒)と yieldMs による自動バックグラウンド化をサポートします。コマンドを発火させ、数秒後にバックグラウンドに移行させ、結果をポーリングします。シンプルで、既知の所要時間の操作に有効です。

オプション B: ACP セッション。 単一のシェルコマンドではなく、ツール使用、ファイル操作、意思決定を伴う可能性のある複雑なマルチステップ作業には、ACP セッションが完全なハーネス分離を提供します。ハーネスは思考し、行動し、メインループに影響を与えずにスタックできます。

オプション C: Cron 調整。 OpenClaw cron ジョブを設定し、インフラストラクチャ状態を定期的にチェックします。デプロイメントの完了を待つ代わりに、数分ごとに調整チェックをスケジュールします。エージェントが起き、ステータスを確認し、行動するか眠りに戻ります。

オプション D: Webhook。 イベント駆動のワークフローでは、外部 cron またはインフラストラクチャのコールバックが OpenClaw の webhook エンドポイント(/hooks/agent)を叩くようにします。Terraform apply が完了したときや Azure デプロイメントが終わったときに webhook を発火させてエージェントを起こします。ポーリングなし、ハングなし。

実践では、私は4つすべてを組み合わせます。重量級の作業に ACP セッション、クイックコマンドに exec バックグラウンド化、調整に cron、状態変化通知に webhook。

トラブルシューティング

権限の失敗

セッション生成直後に AcpRuntimeError が表示される場合、ほぼ常に非インタラクティブ権限のデフォルトです。permissionMode と nonInteractivePermissions の設定を確認してください。

ゾンビセッション

作業を完了したものの適切にクローズされないセッションは、並行スロットを消費します。/acp status で監視し、runtime.ttlMinutes を設定して古いセッションを自動刈り取りします。acp.maxConcurrentSessions の上限に達した場合は、最初にゾンビを確認してください。

ハング種別の区別

すべてのハングが同じではなく、修正は対処している種類に依存します:

  1. メインループがシェルでブロック — エージェント自身がインラインの exec 呼び出し待ちでスタック。これが ACP が解決する問題です。作業をセッションに移してください。
  2. 完了後に ACP セッションがストール — ハーネスは完了したがセッションがクリーンにクローズされていない。/acp close を使うか TTL に任せてください。
  3. ハーネスがネットワークで本当にハング — Claude Code 自身が外部 API 待ちでスタック。/acp cancel でセッションを kill し、根本のネットワーク問題を調査してください。

Claude Code のインストールと認証

これは思ったより多くの人を捕まえます。Claude Code は実際の依存関係です — インストールされていない、認証されていない、または認証トークンが期限切れの場合、ACP セッションは生成時に失敗します。まず /acp doctor を実行してください。常に。

セキュリティの考慮事項

ACP セッションはサンドボックス内ではなく、ホストランタイム上で実行されます。これは仕様です — 実際のインフラストラクチャツールにアクセスする必要があるからです。しかし、セキュリティ境界について考える必要があることを意味します。

webhook については、エンドポイントをループバックまたは Tailnet/プロキシの背後に保持してください。webhook 認証には専用のトークンを使い、外部の発信者が任意の作業を生成できないようエージェントとセッションのルーティングを制限してください。

結論

エージェントのハングはささいな不便さではありません — AI 自動化を本番のインフラストラクチャ作業に対して信頼できないものにする信頼性の問題です。ACP は最もハングしやすい操作に対してプロセス分離、ライフサイクル制御、タイムアウト管理を提供します。

設定は複雑ではありません。魔法でもありません。エージェントオーケストレーションに適用された優れたエンジニアリングプラクティスです: 一つの遅い操作でシステム全体をダウンさせないようにする。

インフラストラクチャ自動化のための AI エージェントワークフローを構築していて信頼性の問題に直面しているなら、お話ししましょう。これは Big Hat Group で我々が行うまさにその種の本番ハードニング作業です。