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 セッションを開始し、集中したままにしてください。」
• 「これをワンショットのクロード コード ACP セッションとして実行し、結果を要約します。」
• 「スレッド内のこのタスクには Gemini CLI を使用し、同じスレッドでフォローアップを続けてください。」

​

ACP とサブエージェント

​

スレッドバインドされたセッション (チャネルに依存しない)

• そのスレッド内のフォローアップ メッセージは、バインドされた ACP セッションにルーティングされます。
• ACP 出力は同じスレッドに返されます。
• フォーカスを解除/閉じる/アーカイブ/アイドル タイムアウトまたは最大有効期限を設定すると、バインドが削除されます。

• acp.enabled=true
• acp.dispatch.enabled はデフォルトでオンです (ACP ディスパッチを一時停止するには false を設定します)
• チャネルアダプター ACP スレッド生成フラグが有効 (アダプター固有)
  • ディスコード: 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>"
• 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 セッション キーを所定の場所にリセットします。
• 一時的なランタイム バインディング (スレッド フォーカス フローによって作成されたものなど) は、存在する場合には引き続き適用されます。

​

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 が必要です。

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

​

オペレーターの煙テスト

• runtime: "acp"
• agentId: "codex"
• mode: "run"
• タスク: 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>.

• 意図的にテストする場合を除き、このスモーク テストは mode: "run" のままにしてください。 スレッドバインドされた永続的な ACP セッション。
• 基本ゲートには streamTo: "parent" は必要ありません。その道は以下によって決まります リクエスター/セッション機能は個別の統合チェックです。
• スレッドバインドされた mode: "session" テストを 2 番目のより充実した統合として扱う 実際の Discord スレッドまたは Telegram トピックから渡されます。

​

サンドボックスの互換性

• エラー: 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".

​

/acp コマンドより

/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>

​

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

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

​

スレッドモードを生成する

• 非スレッド バインディング サーフェスでは、デフォルトの動作は実質的に off になります。
• スレッドバウンドのスポーンにはチャネル ポリシーのサポートが必要です。
  • ディスコード: 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 コマンド クックブック|コマンド |何をするのか |例 |

​

実行時オプションのマッピング

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

​

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

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

​

必要な構成

{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    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,
      },
    },
  },
}

• ディスコード: channels.discord.threadBindings.spawnAcpSessions=true

​

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

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

openclaw plugins install ./extensions/acpx
```次に、バックエンドの健全性を確認します。

```text
/acp doctor

​

acpx コマンドとバージョンの構成

1. コマンドのデフォルトは extensions/acpx/node_modules/.bin/acpx です。
2. 予期されるバージョンのデフォルトは拡張ピンです。
3. スタートアップは、ACP バックエンドをすぐに準備完了として登録します。
4. バックグラウンド保証ジョブが 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 の起動はノンブロッキングのままです。

​

権限の設定

​

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 セッションでは、権限プロンプトをトリガーする書き込みまたは実行が AcpRuntimeError: Permission prompt unavailable in non-interactive mode で失敗する可能性があります。 権限を制限する必要がある場合は、nonInteractivePermissions を deny に設定して、セッションがクラッシュせずに正常に機能を低下させるようにします。

​

トラブルシューティング|症状 |考えられる原因 |修正 |