​

ACP agents

​

빠른 운영자 흐름

1. 세션을 spawn합니다.
   • /acp spawn codex --mode persistent --thread auto
2. 바인딩된 스레드에서 작업합니다(또는 해당 session key를 명시적으로 지정).
3. 런타임 상태를 확인합니다.
   • /acp status
4. 필요에 따라 런타임 옵션을 조정합니다.
   • /acp model <provider/model>
   • /acp permissions <profile>
   • /acp timeout <seconds>
5. 컨텍스트를 교체하지 않고 활성 세션을 살짝 유도합니다.
   • /acp steer tighten logging and continue
6. 작업을 중단합니다.
   • /acp cancel (현재 turn 중단), 또는
   • /acp close (세션 종료 + 바인딩 제거)

​

사람을 위한 빠른 시작

• “Start a persistent Codex session in a thread here and keep it focused.”
• “Run this as a one-shot Claude Code ACP session and summarize the result.”
• “Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread.”

1. runtime: "acp"를 선택합니다.
2. 요청된 harness 대상(agentId, 예: codex)을 해석합니다.
3. 스레드 바인딩이 요청되었고 현재 채널이 이를 지원하면, ACP 세션을 해당 스레드에 바인딩합니다.
4. unfocus/close/expire될 때까지 이후 스레드 메시지를 동일한 ACP 세션으로 라우팅합니다.

​

ACP와 sub-agent 비교

​

스레드 바운드 세션 (채널 불문)

• OpenClaw가 스레드를 대상 ACP 세션에 바인딩합니다.
• 해당 스레드의 후속 메시지는 바인딩된 ACP 세션으로 라우팅됩니다.
• ACP 출력은 동일한 스레드로 다시 전달됩니다.
• unfocus/close/archive/idle-timeout 또는 max-age 만료 시 바인딩이 제거됩니다.

• acp.enabled=true
• acp.dispatch.enabled는 기본적으로 켜져 있음 (ACP dispatch를 일시 중지하려면 false 설정)
• 채널 adapter의 ACP thread-spawn flag 활성화 (adapter별)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

스레드 지원 채널

• session/thread binding capability를 노출하는 모든 채널 adapter
• 현재 내장 지원:
  • Discord threads/channels
  • Telegram topics (groups/supergroups의 forum topic 및 DM topic)
• Plugin 채널도 동일한 binding interface를 통해 지원을 추가할 수 있습니다.

​

채널별 설정

​

바인딩 모델

• bindings[].type="acp"는 영속적인 ACP conversation binding을 표시합니다.
• bindings[].match는 대상 conversation을 식별합니다.
  • Discord channel 또는 thread: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram forum topic: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
• bindings[].agentId는 소유 OpenClaw agent id입니다.
• 선택적 ACP override는 bindings[].acp 아래에 둡니다.
  • mode (persistent 또는 oneshot)
  • label
  • cwd
  • backend

​

에이전트별 런타임 기본값

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (harness 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 세션이 존재하는지 확인합니다.
• 해당 channel 또는 topic의 메시지는 구성된 ACP 세션으로 라우팅됩니다.
• 바인딩된 대화에서는 /new와 /reset이 같은 ACP session key를 제자리에서 reset합니다.
• 임시 런타임 바인딩(예: thread-focus 흐름에서 생성된 것)은 존재할 경우 여전히 적용됩니다.

​

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 대상 harness id. 설정되어 있으면 acp.defaultAgent로 fallback됩니다.
• thread (선택 사항, 기본값 false): 지원되는 경우 thread binding 흐름을 요청합니다.
• mode (선택 사항): run (one-shot) 또는 session (영속).
  • 기본값은 run
  • thread: true이고 mode를 생략하면 OpenClaw는 runtime path에 따라 영속 동작을 기본값으로 삼을 수 있음
  • mode: "session"은 thread: true가 필요
• cwd (선택 사항): 요청된 runtime working directory (backend/runtime policy로 검증됨).
• label (선택 사항): session/banner 텍스트에 사용되는 운영자 표시용 label.
• streamTo (선택 사항): "parent"는 초기 ACP run 진행 요약을 system event로 요청자 session에 다시 스트리밍합니다.
  • 사용 가능한 경우, 허용된 응답에는 전체 relay 이력을 tail할 수 있는 session-scoped JSONL log(<sessionId>.acp-stream.jsonl)를 가리키는 streamLogPath가 포함됩니다.

​

기존 세션 재개

​

운영자 smoke test

1. 대상 호스트에서 배포된 gateway version/commit을 확인합니다.
2. 배포된 소스에 src/gateway/sessions-patch.ts의 ACP lineage acceptance가 포함되어 있는지 확인합니다 (subagent:* or acp:* sessions).
3. 라이브 agent에 대한 임시 ACPX bridge session을 엽니다 (예: razor(main) on jpclawhq).
4. 그 agent에게 다음으로 sessions_spawn을 호출하라고 요청합니다.
   • runtime: "acp"
   • agentId: "codex"
   • mode: "run"
   • task: Reply with exactly LIVE-ACP-SPAWN-OK
5. agent가 다음을 보고하는지 검증합니다.
   • accepted=yes
   • 실제 childSessionKey
   • validator error 없음
6. 임시 ACPX bridge session을 정리합니다.

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 세션을 의도적으로 테스트하는 것이 아니라면, 이 smoke test는 mode: "run"으로 유지하세요.
• 기본 게이트에서는 streamTo: "parent"를 요구하지 마세요. 이 경로는 요청자/session capability에 의존하며 별도의 통합 검사입니다.
• 스레드 바운드 mode: "session" 테스트는 실제 Discord thread 또는 Telegram topic에서 두 번째, 더 풍부한 통합 단계로 취급하세요.

​

Sandbox 호환성

• 요청자 세션이 sandboxed 상태라면, sessions_spawn({ runtime: "acp" })와 /acp spawn 모두에서 ACP spawn이 차단됩니다.
  • Error: 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"를 지원하지 않습니다.
  • Error: 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)
   • 먼저 key 시도
   • 다음으로 UUID 형태의 session id
   • 다음으로 label
2. 현재 스레드 바인딩(이 대화/스레드가 ACP 세션에 바인딩된 경우)
3. 현재 요청자 세션 fallback

​

Spawn 스레드 모드

• non-thread binding surface에서는 기본 동작이 사실상 off입니다.
• 스레드 바운드 spawn에는 채널 정책 지원이 필요합니다.
  • 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 명령 cookbook

​

런타임 옵션 매핑

• /acp model <id>는 runtime config key model에 매핑됩니다.
• /acp permissions <profile>은 runtime config key approval_policy에 매핑됩니다.
• /acp timeout <seconds>는 runtime config key timeout에 매핑됩니다.
• /acp cwd <path>는 runtime cwd override를 직접 갱신합니다.
• /acp set <key> <value>는 일반 경로입니다.
  • 특수 케이스: key=cwd는 cwd override 경로를 사용합니다.
• /acp reset-options는 대상 세션의 모든 runtime override를 지웁니다.

​

acpx harness 지원 (현재)

• 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,
      },
    },
  },
}

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

​

acpx backend용 plugin 설정

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

openclaw plugins install ./extensions/acpx

/acp doctor

​

acpx command 및 version 설정

1. command의 기본값은 extensions/acpx/node_modules/.bin/acpx입니다.
2. 예상 version의 기본값은 extension pin입니다.
3. startup은 ACP backend를 즉시 not-ready 상태로 등록합니다.
4. 백그라운드 ensure job이 acpx --version을 검증합니다.
5. plugin-local binary가 없거나 일치하지 않으면 다음을 실행합니다. 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 directory 기준으로 해석됩니다.
• expectedVersion: "any"는 엄격한 version 일치를 비활성화합니다.
• command가 커스텀 binary/path를 가리키면 plugin-local auto-install은 비활성화됩니다.
• backend health check가 실행되는 동안 OpenClaw startup은 비차단 상태를 유지합니다.

​

권한 설정

​

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 세션에서는 permission prompt를 유발하는 모든 write 또는 exec가 AcpRuntimeError: Permission prompt unavailable in non-interactive mode와 함께 실패할 수 있습니다. 권한을 제한해야 한다면, 세션이 크래시하는 대신 graceful degradation되도록 nonInteractivePermissions를 deny로 설정하세요.

​

Troubleshooting