ACP エージェント

エージェントクライアントプロトコル (ACP) セッションにより、OpenClaw は ACP バックエンドプラグインを通じて外部コーディングハーネス（例: Pi、Claude Code、Codex、OpenCode、Gemini CLI）を実行できます。OpenClaw に対して「これを Codex で実行して」や「スレッドで Claude Code を開始して」と平文で依頼すると、OpenClaw はそのリクエストを ACP ランタイム（ネイティブのサブエージェントランタイムではなく）にルーティングするはずです。

オペレーター向け高速フロー

実用的な /acp 実行手順が必要な場合はこちらを使用してください:

1. セッションを生成:
   • /acp spawn codex --mode persistent --thread auto
2. バインドされたスレッドで作業（またはそのセッションキーを明示的にターゲット）。
3. ランタイム状態を確認:
   • /acp status
4. 必要に応じてランタイムオプションを調整:
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. コンテキストを置き換えずにアクティブなセッションを微調整:
   • /acp steer tighten logging and continue
6. 作業を停止:
   • /acp cancel (現在のターンを停止)、または
   • /acp close (セッションを閉じる + バインディングを削除)

人間向けクイックスタート

自然なリクエストの例:

• 「ここで永続的な Codex セッションをスレッドで開始し、フォーカスを維持してください。」
• 「これをワンショットの Claude Code ACP セッションとして実行し、結果を要約してください。」
• 「このタスクに Gemini CLI を使用し、その後のフォローアップは同じスレッドで行ってください。」

OpenClaw が行うこと:

1. runtime: "acp" を選択。
2. 要求されたハーネスターゲット (agentId、例: codex) を解決。
3. スレッドバインディングが要求され、現在のチャネルがそれをサポートしている場合、ACP セッションをスレッドにバインド。
4. フォローアップのスレッドメッセージを、フォーカスが外れる/閉じられる/期限切れになるまで同じ ACP セッションにルーティング。

ACP 対 サブエージェント

外部ハーネスランタイムが必要な場合は ACP を使用。OpenClaw ネイティブの委任実行が必要な場合はサブエージェントを使用。

サブエージェントも参照してください。

スレッドバインドセッション (チャネル非依存)

チャネルアダプターでスレッドバインディングが有効になっている場合、ACP セッションをスレッドにバインドできます:

• OpenClaw はスレッドをターゲット ACP セッションにバインドします。
• そのスレッド内のフォローアップメッセージはバインドされた ACP セッションにルーティングされます。
• ACP 出力は同じスレッドに返送されます。
• フォーカス解除/閉じる/アーカイブ/アイドルタイムアウトまたは最大経過時間によりバインディングが削除されます。

スレッドバインディングのサポートはアダプター固有です。アクティブなチャネルアダプターがスレッドバインディングをサポートしていない場合、OpenClaw は明確な未サポート/利用不可メッセージを返します。スレッドバインド ACP に必要な機能フラグ:

• acp.enabled=true
• acp.dispatch.enabled はデフォルトでオン (ACP ディスパッチを一時停止するには false に設定)
• チャネルアダプターの ACP スレッド生成フラグが有効 (アダプター固有)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

スレッドをサポートするチャネル

• セッション/スレッドバインディング機能を公開する任意のチャネルアダプター。
• 現在の組み込みサポート:
  • Discord スレッド/チャネル
  • Telegram トピック (グループ/スーパーグループ内のフォーラムトピックおよび DM トピック)
• プラグインチャネルは同じバインディングインターフェースを通じてサポートを追加できます。

チャネル固有の設定

非一時的なワークフローの場合、トップレベルの bindings[] エントリで永続的な ACP バインディングを構成します。

バインディングモデル

• bindings[].type="acp" は永続的な ACP 会話バインディングを示します。
• bindings[].match はターゲット会話を識別:
  • Discord チャネルまたはスレッド: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram フォーラムトピック: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• bindings[].agentId は所有する OpenClaw エージェント ID です。
• オプションの ACP オーバーライドは bindings[].acp の下に配置:
  • mode (persistent または oneshot)
  • label
  • cwd
  • backend

エージェントごとのランタイムデフォルト

agents.list[].runtime を使用してエージェントごとに ACP デフォルトを定義:

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (ハーネス ID、例: codex または claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

ACP バインドセッションのオーバーライド優先順位:

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. グローバル ACP デフォルト (例: acp.backend)

例:

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

動作:

• OpenClaw は使用前に構成された ACP セッションが存在することを保証します。
• そのチャネルまたはトピック内のメッセージは構成された ACP セッションにルーティングされます。
• バインドされた会話では、/new と /reset は同じ ACP セッションキーをその場でリセットします。
• 一時的なランタイムバインディング (例: スレッドフォーカスフローによって作成されたもの) は、存在する場合に引き続き適用されます。

ACP セッションの開始 (インターフェース)

sessions_spawn から

エージェントターンまたはツール呼び出しから ACP セッションを開始するには runtime: "acp" を使用します。

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

注意:

• runtime はデフォルトで subagent なので、ACP セッションには明示的に runtime: "acp" を設定します。
• agentId が省略された場合、OpenClaw は構成時に acp.defaultAgent を使用します。
• mode: "session" には永続的なバインド会話を維持するために thread: true が必要です。

インターフェース詳細:

• task (必須): ACP セッションに送信される初期プロンプト。
• runtime (ACP に必須): "acp" でなければなりません。
• agentId (オプション): ACP ターゲットハーネス ID。設定されている場合は acp.defaultAgent にフォールバック。
• thread (オプション、デフォルト false): サポートされている場合、スレッドバインディングフローを要求。
• mode (オプション): run (ワンショット) または session (永続的)。
  • デフォルトは run
  • thread: true で mode が省略された場合、OpenClaw はランタイムパスごとに永続的な動作をデフォルトとする場合があります
  • mode: "session" には thread: true が必要
• cwd (オプション): 要求されたランタイム作業ディレクトリ (バックエンド/ランタイムポリシーによって検証)。
• label (オプション): オペレーター向けラベル、セッション/バナーテキストで使用。
• streamTo (オプション): "parent" は初期 ACP 実行の進捗概要をシステムイベントとして要求元セッションにストリーム返送します。
  • 利用可能な場合、受け入れられた応答には、完全なリレー履歴を tail できるセッションスコープの JSONL ログ (<sessionId>.acp-stream.jsonl) を指す streamLogPath が含まれます。

サンドボックス互換性

ACP セッションは現在、OpenClaw サンドボックス内ではなく、ホストランタイム上で実行されます。現在の制限:

• 要求元セッションがサンドボックス化されている場合、ACP 生成はブロックされます。
  • エラー: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn で runtime: "acp" の場合、sandbox: "require" はサポートされません。
  • エラー: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

サンドボックス強制実行が必要な場合は runtime: "subagent" を使用してください。

/acp コマンドから

必要に応じてチャットから明示的なオペレーター制御を行うには /acp spawn を使用します。

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --thread here

主要フラグ:

• --mode persistent|oneshot
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

スラッシュコマンドを参照してください。

セッションターゲット解決

ほとんどの /acp アクションはオプションのセッションターゲット (session-key、session-id、session-label) を受け入れます。解決順序:

1. 明示的なターゲット引数 (または /acp steer の --session)
   • キーを試行
   • 次に UUID 形式のセッション ID
   • 次にラベル
2. 現在のスレッドバインディング (この会話/スレッドが ACP セッションにバインドされている場合)
3. 現在の要求元セッションへのフォールバック

ターゲットが解決されない場合、OpenClaw は明確なエラーを返します (Unable to resolve session target: ...)。

スレッド生成モード

/acp spawn は --thread auto|here|off をサポートします。

注意:

• 非スレッドバインディングサーフェスでは、デフォルトの動作は実質的に off です。
• スレッドバインド生成にはチャネルポリシーのサポートが必要:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

ACP コントロール

利用可能なコマンドファミリー:

• /acp spawn
• /acp cancel
• /acp steer
• /acp close
• /acp status
• /acp set-mode
• /acp set
• /acp cwd
• /acp permissions
• /acp timeout
• /acp model
• /acp reset-options
• /acp sessions
• /acp doctor
• /acp install

/acp status は有効なランタイムオプションと、利用可能な場合はランタイムレベルとバックエンドレベルの両方のセッション識別子を表示します。一部のコントロールはバックエンドの機能に依存します。バックエンドがコントロールをサポートしていない場合、OpenClaw は明確な未サポートコントロールエラーを返します。

ACP コマンドクックブック

ランタイムオプションマッピング

/acp には便利なコマンドと汎用セッターがあります。同等の操作:

• /acp model <id> はランタイム設定キー model にマップ。
• /acp permissions <profile> はランタイム設定キー approval_policy にマップ。
• /acp timeout <seconds> はランタイム設定キー timeout にマップ。
• /acp cwd <path> はランタイム cwd オーバーライドを直接更新。
• /acp set <key> <value> は汎用パス。
  • 特殊ケース: key=cwd は cwd オーバーライドパスを使用。
• /acp reset-options はターゲットセッションのすべてのランタイムオーバーライドをクリア。

acpx ハーネスサポート (現在)

現在の acpx 組み込みハーネスエイリアス:

• pi
• claude
• codex
• opencode
• gemini
• kimi

OpenClaw が acpx バックエンドを使用する場合、acpx 設定がカスタムエージェントエイリアスを定義していない限り、agentId にはこれらの値を優先してください。直接の acpx CLI 使用では --agent <command> を介して任意のアダプターをターゲットにすることもできますが、その生のエスケープハッチは acpx CLI 機能です (通常の OpenClaw agentId パスではありません)。

必要な設定

コア ACP ベースライン:

{
  acp: {
    enabled: true,
    // オプション。デフォルトは true; /acp コントロールを維持しながら ACP ディスパッチを一時停止するには false に設定。
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

スレッドバインディング設定はチャネルアダプター固有です。Discord の例:

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

スレッドバインド ACP 生成が機能しない場合は、まずアダプター機能フラグを確認してください:

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

設定リファレンスを参照してください。

acpx バックエンドのプラグインセットアップ

プラグインをインストールして有効化:

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

開発中のローカルワークスペースインストール:

openclaw plugins install ./extensions/acpx

その後、バックエンドの健全性を確認:

/acp doctor

acpx コマンドとバージョン設定

デフォルトでは、acpx プラグイン (公開名 @openclaw/acpx) はプラグインローカルに固定されたバイナリを使用します:

1. コマンドはデフォルトで extensions/acpx/node_modules/.bin/acpx。
2. 期待されるバージョンはデフォルトで拡張機能の固定バージョン。
3. 起動時に ACP バックエンドがすぐに not-ready として登録されます。
4. バックグラウンドの ensure ジョブが acpx --version を検証します。
5. プラグインローカルバイナリが欠落または不一致の場合、以下を実行: npm install --omit=dev --no-save acpx@<pinned> して再検証。

プラグイン設定でコマンド/バージョンをオーバーライドできます:

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

注意:

• command は絶対パス、相対パス、またはコマンド名 (acpx) を受け入れます。
• 相対パスは OpenClaw ワークスペースディレクトリから解決されます。
• expectedVersion: "any" は厳密なバージョン一致を無効にします。
• command がカスタムバイナリ/パスを指す場合、プラグインローカルの自動インストールは無効になります。
• OpenClaw の起動はバックエンド健全性チェックの実行中も非ブロッキングのままです。

プラグインを参照してください。

パーミッション設定

ACP セッションは非対話的に実行されます — ファイル書き込みやシェル実行の許可プロンプトを承認または拒否する TTY はありません。acpx プラグインは、パーミッションの処理方法を制御する 2 つの設定キーを提供します:

permissionMode

ハーネスエージェントがプロンプトなしで実行できる操作を制御します。

nonInteractivePermissions

パーミッションプロンプトが表示されるはずだが、対話型 TTY が利用できない場合 (ACP セッションでは常に該当) の動作を制御します。

設定

プラグイン設定で設定:

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

これらの値を変更した後はゲートウェイを再起動してください。

重要: OpenClaw は現在、デフォルトで permissionMode=approve-reads および nonInteractivePermissions=fail です。非対話型 ACP セッションでは、パーミッションプロンプトをトリガーする書き込みまたは実行は AcpRuntimeError: Permission prompt unavailable in non-interactive mode で失敗する可能性があります。パーミッションを制限する必要がある場合は、セッションがクラッシュするのではなく優雅に劣化するように nonInteractivePermissions を deny に設定してください。

トラブルシューティング

サブエージェントマルチエージェントサンドボックス & ツール