​

ACPエージェント

​

どのページを見るべきか

​

これはそのままで動きますか

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

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

• /acp spawn codex: OpenClawはacpxのブートストラップ準備ができているはずですが、Codex ACPアダプターは初回実行時の取得がまだ必要な場合があります。
• /acp spawn claude: Claude ACPアダプターでも同様で、加えてそのホスト上のClaude側認証も必要です。

​

高速なオペレーターフロー

1. セッションをspawnします:
   • /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 tighten logging and continue
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ランタイムプラグイン
3. Claude ACPアダプター
4. Claude側ランタイム/セッション機構

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

• /acp spawn、バインド可能なセッション、ランタイム制御、または永続的なハーネス作業が必要なら: ACPを使う
• raw CLIを通じたシンプルなローカルテキストフォールバックが必要なら: CLI backendsを使う

​

バインド済みセッション

​

現在の会話へのバインド

• OpenClawは、チャンネルトランスポート、認証、安全性、配信の所有を維持します。
• 現在の会話は、spawnされたACPセッションキーに固定されます。
• その会話内の追加入力メッセージは、同じACPセッションへルーティングされます。
• /newと/resetは、同じバインド済みACPセッションをその場でリセットします。
• /acp closeはセッションを閉じ、現在の会話バインディングを削除します。

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

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

• /acp spawn codex --bind here: このチャットを維持し、Codex ACPセッションをspawnまたは接続し、今後のメッセージをここからそこへルーティングします
• /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出力は同じスレッドへ返送されます。
• unfocus/close/archive/idle-timeoutまたはmax-age期限切れでバインディングは削除されます。

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

​

スレッド対応チャンネル

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

​

チャンネル固有の設定

​

バインディングモデル

• bindings[].type="acp"は永続的なACP会話バインディングを示します。
• bindings[].matchは対象会話を識別します:
  • Discordチャンネルまたはスレッド: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegramフォーラムトピック: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • BlueBubbles DM/グループチャット: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" 安定したグループバインディングにはchat_id:*またはchat_identifier:*を推奨します。
  • iMessage DM/グループチャット: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" 安定したグループバインディングには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セッションキーをその場でリセットします。
• 一時的なランタイムバインディング（たとえばthread-focusフローで作成されたもの）は、存在する場合は引き続き適用されます。
• 明示的なcwdなしのクロスエージェントACP spawnでは、OpenClawはエージェント設定から対象エージェントworkspaceを継承します。
• 継承されたworkspaceパスが存在しない場合は、バックエンドのデフォルトcwdへフォールバックします。存在するがアクセス失敗する場合は、spawnエラーとして表面化します。

​

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

​

sessions_spawnから

{
  "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（任意）: 要求するランタイム作業ディレクトリ（バックエンド/ランタイムポリシーによって検証されます）。省略時、ACP spawnは設定されていれば対象エージェントworkspaceを継承します。継承パスが存在しない場合はバックエンドデフォルトへフォールバックし、実際のアクセスエラーはそのまま返されます。
• label（任意）: セッション/バナーテキストで使用されるオペレーター向けラベル。
• resumeSessionId（任意）: 新しいACPセッションを作成する代わりに既存のACPセッションをresumeします。エージェントはsession/load経由で会話履歴をreplayします。runtime: "acp"が必要です。
• streamTo（任意）: "parent"は初期ACP実行の進捗サマリーをシステムイベントとしてリクエスターセッションへストリーミングします。
  • 利用可能な場合、受理されたレスポンスにはstreamLogPathが含まれます。これはセッションスコープのJSONLログ（<sessionId>.acp-stream.jsonl）を指し、完全なリレー履歴をtailできます。

​

既存セッションをresumeする

{
  "task": "Continue where we left off — fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

• ノートPC上のCodexセッションをスマートフォンへ引き継ぐ — エージェントに中断した場所から再開するよう依頼する
• CLIで対話的に開始したコーディングセッションを、今度はエージェント経由でヘッドレスに継続する
• Gateway再起動やidle timeoutで中断した作業を再開する

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

​

オペレータースモークテスト

1. 対象ホスト上で、デプロイされたGatewayのバージョン/コミットを確認します。
2. デプロイされたソースに、src/gateway/sessions-patch.ts内のACP lineage acceptance （subagent:* or acp:* sessions）が含まれていることを確認します。
3. liveエージェント（たとえば 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
   • validatorエラーなし
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"を必須にしないでください。この経路は リクエスター/セッション機能に依存し、別のintegrationチェックです。
• スレッドバインドされたmode: "session"のテストは、実際のDiscordスレッドまたはTelegramトピックからの、より豊かな第2段階integration として扱ってください。

​

Sandbox互換性

• リクエスターセッションがsandbox化されている場合、sessions_spawn({ runtime: "acp" })と/acp spawnの両方でACP spawnはブロックされます。
  • エラー: 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. 現在のリクエスターセッションへのフォールバック

​

Spawnバインドモード

• --bind hereは、「このチャンネルまたはチャットをCodex対応にする」ための最も単純なオペレーターパスです。
• --bind hereは子スレッドを作成しません。
• --bind hereは、現在の会話バインディングサポートを公開するチャンネルでのみ利用できます。
• 同じ/acp spawn呼び出しで--bindと--threadは併用できません。

​

Spawnスレッドモード

• スレッドバインディングのないサーフェスでは、デフォルト動作は実質的にoffです。
• スレッドバインドspawnにはチャンネルポリシーのサポートが必要です:
  • 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 controlsを維持したまま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バックエンド用プラグインセットアップ

/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プラグインパッケージ内のプラグインローカルnode_modules/.bin/acpxがデフォルトです。
2. 期待バージョンは、拡張機能のpinがデフォルトです。
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 workspaceディレクトリから解決されます。
• expectedVersion: "any"は厳密なバージョン一致を無効化します。
• commandがカスタムバイナリ/パスを指している場合、プラグインローカルの自動インストールは無効になります。
• バックエンド健全性チェック実行中も、OpenClaw起動は非ブロッキングのままです。

​

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

​

プラグインツールMCPブリッジ

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

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

• これはACPハーネスのツールサーフェスを拡張します。
• ACPエージェントは、gatewayですでに有効なプラグインツールにのみアクセスできます。
• これは、それらのプラグインを OpenClaw自体で実行させるのと同じ信頼境界として扱ってください。
• 有効化する前に、インストール済みプラグインを確認してください。

​

ランタイムタイムアウト設定

openclaw config set plugins.entries.acpx.config.timeoutSeconds 180

​

権限設定

​

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に設定してください。

​

トラブルシューティング