ACP Agents

Agent Client Protocol (ACP) 세션을 사용하면 OpenClaw가 외부 코딩 하니스(Pi, Claude Code, Codex, OpenCode, Gemini CLI 등)를 ACP 백엔드 플러그인을 통해 실행할 수 있습니다. 사용자가 자연어로 “Codex로 이거 돌려” 또는 “스레드에서 Claude Code 시작해”라고 하면, OpenClaw는 이를 네이티브 sub-agent 런타임이 아니라 ACP 런타임으로 라우팅해야 합니다.

빠른 운영 흐름

세션 시작:
- /acp spawn codex --mode persistent --thread auto
바인딩된 스레드에서 작업하거나 해당 세션 키를 명시적으로 지정
런타임 상태 확인:
- /acp status
필요 시 옵션 조정:
- /acp model <provider/model>
- /acp permissions <profile>
- /acp timeout <seconds>
컨텍스트를 버리지 않고 방향만 수정:
- /acp steer tighten logging and continue
작업 중지:
- /acp cancel 또는
- /acp close

ACP와 sub-agents의 차이

ACP는 외부 하니스 런타임이 필요할 때 사용하고, sub-agent는 OpenClaw 네이티브 위임 실행에 사용합니다.

항목	ACP 세션	Sub-agent 실행
런타임	ACP backend plugin (예: acpx)	OpenClaw 네이티브 sub-agent runtime
세션 키	`agent:<agentId>:acp:<uuid>`	`agent:<agentId>:subagent:<uuid>`
주요 명령	`/acp ...`	`/subagents ...`
spawn 도구	`sessions_spawn` + `runtime:"acp"`	기본 `sessions_spawn`

Thread-bound ACP

채널 어댑터에서 thread binding이 활성화돼 있으면 ACP 세션을 스레드에 바인딩할 수 있습니다.

OpenClaw가 스레드를 대상 ACP 세션에 바인딩
후속 메시지는 같은 ACP 세션으로 라우팅
출력도 같은 스레드로 전달
unfocus/close/archive/idle-timeout/max-age 만료 시 바인딩 제거

필수 플래그:

acp.enabled=true
acp.dispatch.enabled=true (기본값)
채널별 ACP thread spawn 플래그
- Discord: channels.discord.threadBindings.spawnAcpSessions=true
- Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

채널별 지속형 ACP 바인딩

비일회성 워크플로에는 최상위 bindings[]의 type: "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 agent ID
선택적 ACP override: bindings[].acp
- mode
- label
- cwd
- backend

에이전트별 런타임 기본값

agents.list[].runtime에 ACP 기본값을 둘 수 있습니다.

agents.list[].runtime.type="acp"
agents.list[].runtime.acp.agent
agents.list[].runtime.acp.backend
agents.list[].runtime.acp.mode
agents.list[].runtime.acp.cwd

우선순위:

bindings[].acp.*
agents.list[].runtime.acp.*
전역 acp.*

`/acp spawn`

명시적 운영 제어가 필요할 때는 채팅에서 /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)을 받습니다. 해석 순서:

명시적 대상 인수 (/acp steer는 --session)
현재 thread binding
현재 requester session fallback

해결되지 않으면 Unable to resolve session target: ... 오류를 반환합니다.

`/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는 런타임 옵션과 가능한 경우 runtime/backend 양쪽 세션 식별자를 보여줍니다.

런타임 옵션 매핑

/acp model <id> → model
/acp permissions <profile> → approval_policy
/acp timeout <seconds> → timeout
/acp cwd <path> → cwd override
/acp set <key> <value> → 일반 setter
/acp reset-options → 대상 세션의 모든 runtime override 제거

acpx 지원

현재 acpx 내장 alias:

pi
claude
codex
opencode
gemini
kimi

일반적인 agentId에는 위 값을 우선 사용하십시오.

기본 설정

{
  acp: {
    enabled: true,
    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,
      },
    },
  },
}

플러그인 설정

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

개발 중 로컬 설치:

openclaw plugins install ./extensions/acpx

그 다음 /acp doctor로 상태를 확인합니다.

권한 설정

ACP 세션은 비대화형으로 실행되므로 TTY 승인이 없습니다.

`permissionMode`

approve-all
approve-reads
deny-all

`nonInteractivePermissions`

fail (기본값)
deny

샌드박스 호환성

ACP 세션은 현재 OpenClaw sandbox 안이 아니라 호스트 런타임에서 실행됩니다.

sandboxed requester session에서는 runtime:"acp" spawn이 차단됩니다.
sessions_spawn에서 runtime:"acp"와 sandbox:"require" 조합은 지원되지 않습니다.

샌드박스 강제가 필요하면 runtime:"subagent"를 사용하십시오.

Overview

Built-in tools

Browser

Agent coordination

Skills

Extensions

Automation

Media and devices

ACP Agents

ACP Agents

빠른 운영 흐름

ACP와 sub-agents의 차이

Thread-bound ACP

채널별 지속형 ACP 바인딩

바인딩 모델

에이전트별 런타임 기본값

`/acp spawn`

세션 대상 해석

`/acp` 명령 모음

런타임 옵션 매핑

acpx 지원

기본 설정

플러그인 설정

권한 설정

`permissionMode`

`nonInteractivePermissions`

샌드박스 호환성

관련 문서

최근 업데이트 메모

Overview

Built-in tools

Browser

Agent coordination

Skills

Extensions

Automation

Media and devices

Documentation Index

​ACP Agents

​빠른 운영 흐름

​ACP와 sub-agents의 차이

​Thread-bound ACP

​채널별 지속형 ACP 바인딩

​바인딩 모델

​에이전트별 런타임 기본값

​/acp spawn

​세션 대상 해석

​/acp 명령 모음

​런타임 옵션 매핑

​acpx 지원

​기본 설정

​플러그인 설정

​권한 설정

​permissionMode

​nonInteractivePermissions

​샌드박스 호환성

​관련 문서

​최근 업데이트 메모

ACP Agents

빠른 운영 흐름

ACP와 sub-agents의 차이

Thread-bound ACP

채널별 지속형 ACP 바인딩

바인딩 모델

에이전트별 런타임 기본값

`/acp spawn`

세션 대상 해석

`/acp` 명령 모음

런타임 옵션 매핑

acpx 지원

기본 설정

플러그인 설정

권한 설정

`permissionMode`

`nonInteractivePermissions`

샌드박스 호환성

관련 문서

최근 업데이트 메모