​

ACPエージェント

​

どのページを見ればよいですか？

​

これはそのまま使えますか？

• 新規インストールでは、同梱の acpx ランタイムpluginがデフォルトで有効になっています。
• 同梱の acpx pluginは、pluginローカルに固定された acpx バイナリを優先します。
• 起動時に、OpenClawはそのバイナリをprobeし、必要に応じて自己修復します。
• 準備状況をすばやく確認したいなら、まず /acp doctor から始めてください。

• 対象ハーネス用アダプターが、そのハーネスの初回利用時に npx でオンデマンド取得されることがあります。
• ベンダー認証は、そのハーネスのためにホスト上に存在している必要があります。
• ホストにnpm/ネットワークアクセスがない場合、初回のアダプター取得は、キャッシュを事前に温めるか別の方法でアダプターをインストールするまで失敗することがあります。

• /acp spawn codex: OpenClawは acpx をブートストラップできる状態のはずですが、Codex ACPアダプターは初回取得が必要な場合があります。
• /acp spawn claude: Claude ACPアダプターについても同様で、さらにそのホスト上でClaude側認証も必要です。

​

実運用向けの簡易フロー

1. セッションを起動します:
   • /acp spawn codex --bind here
   • /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 logging をもっと絞って続けて
6. 作業を停止します:
   • /acp cancel（現在のターンを停止）、または
   • /acp close（セッションを閉じてバインドを削除）

​

人向けクイックスタート

• 「このDiscordチャネルをCodexにバインドして。」
• 「ここでスレッド内に永続的なCodexセッションを開始して、集中させて。」
• 「これを単発のClaude Code ACPセッションとして実行して、結果を要約して。」
• 「このiMessageチャットをCodexにバインドして、以後のやり取りも同じworkspaceで続けて。」
• 「このタスクにはGemini CLIをスレッドで使って、その後のやり取りも同じスレッドで続けて。」

1. runtime: "acp" を選択する。
2. 要求されたハーネスターゲット（agentId、たとえば codex）を解決する。
3. 現在の会話へのバインドが要求され、かつアクティブチャネルがそれをサポートしているなら、ACPセッションをその会話にバインドする。
4. そうでなければ、スレッドバインドが要求され、かつ現在のチャネルがそれをサポートしているなら、ACPセッションをそのスレッドにバインドする。
5. その後のバインド済みメッセージを、フォーカス解除・クローズ・期限切れになるまで同じACPセッションへルーティングする。

​

ACPとsub-agentの違い

​

ACPがClaude Codeを実行する仕組み

1. OpenClaw ACPセッション制御プレーン
2. 同梱の acpx ランタイムplugin
3. Claude ACPアダプター
4. Claude側のランタイム/セッション機構

• ACP Claudeは、直接の claude-cli/... フォールバックランタイムとは別物です。
• ACP Claudeは、ACP制御、セッション再開、background task追跡、および任意の会話/スレッドバインドを備えたハーネスセッションです。
• claude-cli/... はテキスト専用のローカルCLIバックエンドです。CLI Backends を参照してください。

• /acp spawn、バインド可能なセッション、ランタイム制御、または永続的なハーネス作業が欲しい: ACPを使う
• 生のCLI経由で単純なローカルテキストフォールバックが欲しい: CLIバックエンドを使う

​

バインド済みセッション

​

現在の会話へのバインド

• OpenClawはチャネルトランスポート、認証、安全性、配信を引き続き管理します。
• 現在の会話は、起動されたACPセッションキーに固定されます。
• その会話での以後のメッセージは、同じACPセッションへルーティングされます。
• /new と /reset は、同じバインド済みACPセッションをその場でリセットします。
• /acp close はセッションを閉じ、現在の会話バインドを削除します。

• --bind here は同じチャット画面を維持します。Discordでは、現在のチャネルはそのまま現在のチャネルです。
• --bind here は、新しい作業を起動する場合には新しいACPセッションを作成することがあります。バインドはそのセッションを現在の会話に接続します。
• --bind here 自体はDiscordの子スレッドやTelegramトピックを作成しません。
• ACPランタイムは、独自の作業ディレクトリ（cwd）やバックエンド管理workspaceをディスク上に持つことができます。そのランタイムworkspaceはチャット画面とは別であり、新しいメッセージスレッドを意味するものではありません。
• 別のACPエージェントに起動し、--cwd を渡さない場合、OpenClawはデフォルトで要求元ではなく 対象エージェントの workspaceを継承します。
• 継承されたworkspaceパスが存在しない場合（ENOENT/ENOTDIR）、OpenClawは誤ったツリーを黙って再利用するのではなく、バックエンドのデフォルトcwdにフォールバックします。
• 継承されたworkspaceが存在していてもアクセスできない場合（たとえば EACCES）、起動は cwd を捨てずに実際のアクセスエラーを返します。

• チャット画面: 人が会話を続ける場所（Discord channel、Telegram topic、iMessage chat）
• ACPセッション: OpenClawがルーティング先とする、永続的なCodex/Claude/Geminiランタイム状態
• 子スレッド/トピック: --thread ... によってのみ作成される任意の追加メッセージ画面
• ランタイムworkspace: ハーネスが実行されるファイルシステム上の場所（cwd、リポジトリcheckout、バックエンドworkspace）

• /acp spawn codex --bind here: このチャットを維持し、Codex ACPセッションを起動または接続し、以後のメッセージをここからそこへルーティングする
• /acp spawn codex --thread auto: OpenClawが子スレッド/トピックを作成し、そこにACPセッションをバインドすることがあります
• /acp spawn codex --bind here --cwd /workspace/repo: 上と同じチャットバインドですが、Codexは /workspace/repo で実行されます

• 現在の会話バインド対応を公開しているチャット/メッセージチャネルでは、共有の会話バインド経路を通じて --bind here を使用できます。
• 独自のスレッド/トピック意味論を持つチャネルでも、同じ共有インターフェースの背後でチャネル固有の正規化を提供できます。
• --bind here は常に「現在の会話をその場でバインドする」を意味します。
• 汎用の現在会話バインドは、共有のOpenClawバインドストアを使用し、通常のGateway再起動でも維持されます。

• /acp spawn では --bind here と --thread ... は相互排他的です。
• Discordでは、--bind here は現在のチャネルまたはスレッドをその場でバインドします。spawnAcpSessions が必要なのは、--thread auto|here 用にOpenClawが子スレッドを作成する必要がある場合だけです。
• アクティブチャネルが現在会話のACPバインドを公開していない場合、OpenClawは明確な未対応メッセージを返します。
• resume と「新しいセッション」についての問いはACPセッションの問いであり、チャネルの問いではありません。現在のチャット画面を変えずにランタイム状態を再利用または置き換えることができます。

​

スレッドにバインドされたセッション

• OpenClawはスレッドを対象ACPセッションにバインドします。
• そのスレッドでの以後のメッセージは、バインド済みACPセッションへルーティングされます。
• ACPの出力は同じスレッドに返されます。
• フォーカス解除/クローズ/アーカイブ/アイドルタイムアウトまたは最大有効期間の期限切れでバインドは削除されます。

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

​

スレッド対応チャネル

• セッション/スレッドバインド機能を公開する任意のチャネルアダプター。
• 現在の組み込みサポート:
  • Discordスレッド/チャネル
  • Telegramトピック（group/supergroupのforum topicとDM topic）
• pluginチャネルも同じバインドインターフェースを通じてサポートを追加できます。

​

チャネル固有設定

​

バインディングモデル

• bindings[].type="acp" は永続的なACP会話バインドを示します。
• bindings[].match は対象会話を識別します:
  • Discordチャネルまたはスレッド: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram forum topic: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • BlueBubbles DM/group chat: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" 安定したgroupバインドには chat_id:* または chat_identifier:* を優先してください。
  • iMessage DM/group chat: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" 安定したgroupバインドには chat_id:* を優先してください。
• bindings[].agentId は所有するOpenClawエージェントIDです。
• 任意のACP上書きは bindings[].acp の下に置きます:
  • mode（persistent または oneshot）
  • label
  • cwd
  • backend

​

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

• 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

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セッションキーをその場でリセットします。
• 一時的なランタイムバインド（たとえばスレッドfocusフローで作成されたもの）も、存在する場合は引き続き適用されます。
• 明示的な cwd なしでエージェント間ACP起動を行うと、OpenClawはエージェント設定から対象エージェントworkspaceを継承します。
• 継承workspaceパスが存在しない場合はバックエンドデフォルトcwdにフォールバックし、実際のアクセス失敗は起動エラーとして表面化します。

​

ACPセッションを開始する（インターフェース）

​

sessions_spawn から

{
  "task": "リポジトリを開いて失敗しているテストを要約して",
  "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（任意）: 要求するランタイム作業ディレクトリ（バックエンド/ランタイムポリシーで検証されます）。省略時、設定されていればACP起動は対象エージェントworkspaceを継承します。継承パスが存在しない場合はバックエンドデフォルトにフォールバックし、実際のアクセスエラーは返されます。
• label（任意）: セッション/バナー文言で使われる運用者向けラベル。
• resumeSessionId（任意）: 新規作成ではなく既存のACPセッションを再開します。エージェントは session/load 経由で会話履歴を再生します。runtime: "acp" が必要です。
• streamTo（任意）: "parent" は、初期ACP実行の進捗サマリーをシステムイベントとして要求元セッションへストリームします。
  • 利用可能な場合、受理されたレスポンスには streamLogPath が含まれ、セッション単位JSONLログ（<sessionId>.acp-stream.jsonl）を指します。完全な中継履歴を追跡できます。

​

既存セッションを再開する

{
  "task": "前回の続きから始めて — 残っているテスト失敗を修正して",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

• Codexセッションをラップトップからスマートフォンへ引き継ぐ — エージェントに中断地点から再開するよう伝える
• CLIで対話的に始めたコーディングセッションを、今度はエージェント経由でヘッドレスに継続する
• Gateway再起動やアイドルタイムアウトで中断した作業を再開する

• resumeSessionId には runtime: "acp" が必要です。sub-agentランタイムで使うとエラーを返します。
• resumeSessionId は上流ACP会話履歴を復元します。thread と mode は新しく作成するOpenClawセッションに通常どおり適用されるため、mode: "session" には引き続き thread: true が必要です。
• 対象エージェントは session/load をサポートしている必要があります（CodexとClaude Codeはサポートします）。
• セッションIDが見つからない場合、起動は明確なエラーで失敗します。新規セッションへの黙示的フォールバックは行われません。

​

運用者向けスモークテスト

1. 対象ホスト上でデプロイ済みGatewayのバージョン/コミットを確認する。
2. デプロイ済みソースに src/gateway/sessions-patch.ts のACP系統受け入れ （subagent:* or acp:* sessions）が含まれていることを確認する。
3. 実際のエージェント（たとえば jpclawhq 上の razor(main)）へ一時的なACPXブリッジセッションを開く。
4. そのエージェントに、次の内容で sessions_spawn を呼ぶよう依頼する:
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. エージェントが次を報告することを確認する:
   • accepted=yes
   • 実在する childSessionKey
   • バリデーターエラーなし
6. 一時的なACPXブリッジセッションをクリーンアップする。

Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
Set the task to: "Reply with exactly LIVE-ACP-SPAWN-OK".
Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exact text or none>.

• このスモークテストは、意図的にスレッドにバインドされた永続ACPセッションを試しているのでない限り、mode: "run" のままにしてください。
• 基本ゲートでは streamTo: "parent" を必須にしないでください。その経路は要求元/セッション機能に依存するため、別の統合チェックです。
• スレッドにバインドされた mode: "session" テストは、実際のDiscordスレッドやTelegramトピックからの第2段階の、より充実した統合パスとして扱ってください。

​

サンドボックス互換性

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

​

/acp コマンドから

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

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

​

セッション対象の解決

1. 明示的な対象引数（または /acp steer 用の --session）
   • まずkeyを試す
   • 次にUUID形のsession idを試す
   • 次にlabelを試す
2. 現在のスレッドバインド（この会話/スレッドがACPセッションにバインドされている場合）
3. 現在の要求元セッションへのフォールバック

​

起動バインドモード

• --bind here は「このチャネルまたはチャットをCodex対応にする」ための最も簡単な運用経路です。
• --bind here は子スレッドを作成しません。
• --bind here は、現在の会話バインド対応を公開しているチャネルでのみ利用可能です。
• --bind と --thread は同じ /acp spawn 呼び出しでは併用できません。

​

起動スレッドモード

• スレッドバインドのない画面では、デフォルト挙動は実質的に off です。
• スレッドにバインドされた起動にはチャネルポリシーサポートが必要です:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• 子スレッドを作らずに現在の会話を固定したい場合は --bind here を使ってください。

​

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コマンド早見表

​

ランタイムオプション対応

• /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ハーネスサポート（現在）

• claude
• codex
• copilot
• cursor（Cursor CLI: cursor-agent acp）
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• pi
• qwen

​

必須設定

{
  acp: {
    enabled: true,
    // 任意。デフォルトはtrueです。/acp制御を維持したままACP dispatchを一時停止するにはfalseに設定します。
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "openclaw",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

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

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

​

acpxバックエンドのplugin設定

/acp doctor

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

openclaw plugins install ./path/to/local/acpx-plugin

/acp doctor

​

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

1. コマンドは、ACPX pluginパッケージ内のpluginローカル node_modules/.bin/acpx をデフォルトにします。
2. 期待バージョンはextensionの固定値をデフォルトにします。
3. 起動時にACPバックエンドを即座に準備未完了として登録します。
4. バックグラウンドensureジョブが acpx --version を検証します。
5. pluginローカルバイナリが存在しないか不一致の場合、次を実行します: npm install --omit=dev --no-save acpx@<pinned> を実行して再検証します。

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

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

​

依存関係の自動インストール

​

pluginツールMCPブリッジ

openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true

• openclaw-plugin-tools という名前の組み込みMCPサーバーをACPXセッション ブートストラップに注入します。
• インストール済みかつ有効なOpenClaw pluginsによってすでに登録されているpluginツールを公開します。
• この機能を明示的なデフォルトオフのままに保ちます。

• これによりACPハーネスのツール対象範囲が広がります。
• ACPエージェントがアクセスできるのは、gateway内ですでに有効なpluginツールだけです。
• これは、それらのpluginsをOpenClaw自身で実行させるのと同じ信頼境界として扱ってください。
• 有効化前にインストール済みpluginsを確認してください。

​

権限設定

​

permissionMode

​

nonInteractivePermissions

​

設定

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セッションでは、権限プロンプトを発生させる書き込みやexecは AcpRuntimeError: Permission prompt unavailable in non-interactive mode で失敗する可能性があります。 権限を制限したい場合は、セッションがクラッシュする代わりに穏当に劣化するよう nonInteractivePermissions を deny に設定してください。

​

トラブルシューティング