OpenClawのACPエージェント

ターミナルではなくTelegramのメッセージからClaude CodeやGemini CLIを動かしたい場合、OpenClawはAgent Client Protocolを介してそれを実現できます。ACPセッションは、本物の外部ハーネスをGatewayホスト上のプロセスとして起動し、起動のたびにそれをバックグラウンドタスクとして追跡します。また、会話やスレッドをバインドして、後続のメッセージが同じハーネスに届き続けるようにできます。まずランタイムプラグインが必要で、さらにいくつかの条件によって、エージェントがそもそもこの経路の存在を知らされるかどうかが決まります。

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

• パッケージ版のインストールでは、npmのopenclawスコープで公開されている公式のacpxランタイムプラグインを使います。必要なのは2つのコマンドで、そのスコープ付きパッケージを指定したopenclaw plugins installと、続くopenclaw config set plugins.entries.acpx.enabled trueです。ソースからチェックアウトした場合は、代わりにpnpm installの後でローカルのextensions/acpxワークスペースプラグインを使えます。その後、/acp doctorで準備状況を確認するか、/acp installを実行して、OpenClawに決定論的なインストール手順と有効化手順を表示させます。
• plugins.allowが設定されている場合、それはヒントではなく制限的なプラグイン一覧であり、acpxを含めなければ、インストール済みのACPバックエンドは意図的にブロックされます。これは壊れたインストールと最も誤解されやすい初回実行時の失敗で、ACPランタイムバックエンドが設定されていないというエラーとして現れます。/acp doctorは、推測に任せるのではなく、許可リストに欠けているエントリーを報告してくれます。
• acpxプラグインはACPランタイムを直接組み込んでいるため、別途設定すべきacpxバイナリやバージョンはありません。Gatewayの起動時に組み込みバックエンドを登録し、gatewayのready信号の前にヘルスプローブを1回待ちます。このプローブは失敗時の診断情報も提供します。待ち時間の上限はplugins.entries.acpx.config.timeoutSecondsで決まり、デフォルトは120秒です。これは、Gemini CLIのような遅いハーネスでもACPの起動と初期化を完了できるようにするためです。
• Codex ACPアダプターはacpxプラグインに同梱されており、可能な場合はローカルで起動します。その際は分離されたCODEX_HOMEで動作し、OpenClawはそこに信頼済みプロジェクトのtrustエントリーと、安全なモデルおよびプロバイダーのルーティング設定をコピーします。一方、認証、通知、フックはホスト側の設定にのみ残ります。その他のハーネスアダプターは初回使用時にnpxでオンデマンド取得される場合があるため、npmやネットワークにアクセスできないホストでは、キャッシュを事前に温めておくか、別の方法でアダプターをインストールするまで、その取得は失敗します。

いずれかの条件を満たさない場合、ACPのスキルとsessions_spawnのACPガイダンスは非表示のままとなり、エージェントが利用できないバックエンドを提案しないようになっています。

ACPのスキルが見えなくなる理由

条件はすべて明記されています。ACPが有効であること、ディスパッチが無効化されていないこと、現在のセッションがサンドボックスによってブロックされていないこと、そしてランタイムバックエンドが読み込まれていて正常であることです。一度もACPの起動を提案してこないエージェントは、たいていあなたを無視しているのではなく、自身の設定を正確に伝えています。この2つの側面は失敗の仕方が異なります。acp.dispatch.enabled=falseは、スレッドへの自動ACPディスパッチを一時停止しますが、runtime acpを指定した明示的なsessions_spawn呼び出しを隠したりブロックしたりはしません。一方、サンドボックス内の要求元は、ACPランタイムがホスト側で動くため、即座に拒否されます。サンドボックス化されたセッションからの場合、ドキュメントに記載された解決策はsubagentランタイムです。

前提条件のチェックリスト

• OpenClawを疑う前に、/acp doctorが有効かつ正常なバックエンドを報告していること、acp.allowedAgentsの許可リストが設定されている場合はターゲットIDがそこで許可されていること、そしてハーネスのコマンドがGatewayホスト上で実際に起動できることを確認してください。これらにはそれぞれ固有のエラーテキストがあり、1つの汎用的な失敗にまとめられてはいないため、表示されるメッセージの時点で原因がかなり絞り込まれます。
• ターゲットとするハーネスのプロバイダー認証が、あらかじめホスト上に存在している必要があります。claude、codex、gemini、opencode、droidなどは、それぞれ独自のログインを持っています。ベンダーの認証エラーは、OpenClawは正常で、ターゲットのCLIまたはプロバイダーにログインしていないだけであることを意味します。これはOpenClawの設定を編集するのではなく、ログインするか、Gatewayホストの環境にプロバイダーのキーを渡すことで解決します。
• 選択したモデルがそのハーネスに存在している必要があります。モデルIDはハーネス間で共通ではなく、モデルの制御はアダプターの機能に依存するためです。ACPのmodels機能も独自の起動時モデルフラグも公開していないハーネスは、特定のモデルに固定することがまったくできません。要求するcwdは存在し、アクセス可能でなければなりません。そうでない場合はcwdを省略し、バックエンドのデフォルトを使わせます。

設定を書く前に、選択を左右する点が1つあります。OpenClawのプラグインツールと組み込みのOpenClawツールは、デフォルトではACPハーネスに公開されず、これを変える2つのMCPブリッジは明示的に設定するもので、デフォルトではオフです。OpenClaw独自のツールを使う、OpenClawネイティブの委任実行が必要なら、それはOpenClawのサブエージェントの実行であり、専用のセッションキーと専用のスラッシュコマンドを持ちます。ローカルのAI CLIをテキスト専用のフォールバックモデルとして使いたいだけなら、OpenClawのCLIバックエンドはACPでもハーネスランタイムでもなく、OpenClawのツールもACPの制御もありません。

17個のハーネスターゲットID

acpxバックエンドで/acp spawnに、またはsessions_spawnのagentIdとして渡すIDは次のとおりです：claude、codex、copilot、cursor、droid、fast-agent、gemini、iflow、kilocode、kimi、kiro、mux、opencode、openclaw、qoder、qwen、trae。claudeはホスト上のClaude Code認証を、copilotはCopilot CLIまたはランタイムへのログインを必要とし、cursorはcursor-agent acpを実行します。droidはFactoryまたはDroidの認証、あるいはハーネス環境のFACTORY_API_KEYを、geminiはGemini CLIの認証またはAPIキーの設定を、opencodeはOpenCode CLIまたはプロバイダーの認証を必要とします。openclawはGatewayブリッジで、ACP対応のハーネスがOpenClaw Gatewayのセッションに応答できるようにします。codexは明示的なACPフォールバックで、ネイティブの/codex経路が使えない場合か、ACPが名指しで要求された場合にのみ使われます。piもacpxバックエンドに登録されていますが、同じ意味でのコーディングハーネスではありません。すべての起動はOpenClawのバックグラウンドタスクに記録され、ハーネスレベルの設定がOpenClawのexec承認と並んで置かれているのがOpenClawの権限モードです。ACPセッションには対話型のTTYがないため、書き込みや実行の多いコーディングには、通常、対話なしで進められるプロファイルが必要です。

Dialiでは

DialiはOpenClawをお客様に代わってホストし、各顧客は共有アシスタントの一部ではなく、自分専用のアシスタントを運用します。エンジンの設定はダッシュボードから生成され、リリースのたびに置き換えられるため、ポリシーキーは、自分で覚えておかなければならないマシン上で手作業で編集するのではなく、自動的に書き込まれます。状態は永続ボリュームに保存され、これによってアップグレード後もセッションとその履歴が保たれます。毎日のスナップショットとワンクリック復元は、「バックアップ」アドオン（Maxに含まれます）で利用できます。ホスト型エンジンで何がカバーされるかはDialiのマネージドOpenClawホスティングに、プランはDialiの料金にまとめています。

• acpxは2つのコマンドでインストールし、何よりも先に/acp doctorを実行します。
• ACPのガイダンスが非表示なのは、機能がないからではなく、条件を満たしていないからです。
• 17個のハーネスID。それぞれがホスト上で独自のログインを持ちます。