ACP 에이전트

Agent Client Protocol (ACP) 세션을 사용하면 OpenClaw에서 ACP 백엔드 플러그인을 통해 외부 코딩 하네스(예: Pi, Claude Code, Codex, OpenCode, Gemini CLI)를 실행할 수 있습니다.

자연어로 “이걸 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는 기본적으로 활성화 (false로 설정하여 ACP 디스패치 일시 중지)
• 채널 어댑터 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에서

runtime: "acp"를 사용하여 에이전트 턴이나 도구 호출에서 ACP 세션을 시작합니다.

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

참고:

• runtime은 기본적으로 subagent이므로, ACP 세션의 경우 runtime: "acp"를 명시적으로 설정하세요.
• agentId가 생략되면, 구성된 경우 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가 생략되면, 런타임 경로에 따라 영구 동작이 기본값일 수 있음
  • mode: "session"은 thread: true가 필요
• cwd (선택): 요청된 런타임 작업 디렉터리 (백엔드/런타임 정책에 의해 검증).
• label (선택): 세션/배너 텍스트에 사용되는 운영자용 레이블.
• resumeSessionId (선택): 새 세션을 만드는 대신 기존 ACP 세션을 재개. 에이전트가 session/load를 통해 대화 기록을 재생합니다. runtime: "acp"가 필요합니다.
• streamTo (선택): "parent"는 초기 ACP 실행 진행 요약을 시스템 이벤트로 요청자 세션에 스트리밍합니다.
  • 가능한 경우, 수락된 응답에 세션 범위 JSONL 로그(<sessionId>.acp-stream.jsonl)를 가리키는 streamLogPath가 포함되어 전체 릴레이 기록을 tail할 수 있습니다.

기존 세션 재개

resumeSessionId를 사용하여 새로 시작하는 대신 이전 ACP 세션을 이어서 진행합니다. 에이전트가 session/load를 통해 대화 기록을 재생하므로, 이전 컨텍스트를 완전히 유지한 채로 시작합니다.

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

일반적인 사용 사례:

• 노트북에서 시작한 Codex 세션을 휴대폰으로 넘기기 — 에이전트에게 중단한 곳부터 이어서 진행하도록 지시
• CLI에서 대화형으로 시작한 코딩 세션을 에이전트를 통해 헤드리스로 이어서 진행
• 게이트웨이 재시작이나 유휴 타임아웃으로 중단된 작업 이어받기

참고:

• resumeSessionId는 runtime: "acp"가 필요합니다 — 서브 에이전트 런타임과 함께 사용하면 오류가 반환됩니다.
• resumeSessionId는 업스트림 ACP 대화 기록을 복원합니다. thread와 mode는 생성 중인 새 OpenClaw 세션에 정상적으로 적용되므로, mode: "session"은 여전히 thread: true가 필요합니다.
• 대상 에이전트가 session/load를 지원해야 합니다(Codex와 Claude Code가 지원).
• 세션 ID를 찾을 수 없으면, 새 세션으로의 자동 폴백 없이 명확한 오류와 함께 생성이 실패합니다.

운영자 스모크 테스트

게이트웨이 배포 후 ACP 생성이 단위 테스트만 통과하는 것이 아니라 실제로 엔드투엔드로 동작하는지 빠르게 확인하고 싶을 때 사용합니다.

권장 검증 절차:

1. 대상 호스트에서 배포된 게이트웨이 버전/커밋 확인.
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 주제에서의 두 번째, 더 풍부한 통합 패스로 취급하세요.

샌드박스 호환성

ACP 세션은 현재 OpenClaw 샌드박스가 아닌 호스트 런타임에서 실행됩니다.

현재 제한 사항:

• 요청자 세션이 샌드박스인 경우, 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.
• 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 sessions는 현재 바인딩된 세션 또는 요청자 세션의 저장소를 읽습니다. session-key, session-id, 또는 session-label 토큰을 허용하는 명령은 에이전트별 커스텀 session.store 루트를 포함하여 게이트웨이 세션 검색을 통해 대상을 확인합니다.

런타임 옵션 매핑

/acp에는 편의 명령과 일반 setter가 있습니다.

동등한 작업:

• /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 백엔드를 준비되지 않은 상태로 즉시 등록.
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 시작은 차단되지 않습니다.

플러그인을 참조하세요.

권한 설정

ACP 세션은 비대화형으로 실행됩니다 — 파일 쓰기 및 셸 실행 권한 프롬프트를 승인하거나 거부할 TTY가 없습니다. acpx 플러그인은 권한 처리 방식을 제어하는 두 가지 설정 키를 제공합니다:

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로 설정하세요.

문제 해결