메인 콘텐츠로 건너뛰기

​
ACP Agents

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

​
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
관련 문서: Sub-agents

​
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
우선순위:
  1. bindings[].acp.*
  2. agents.list[].runtime.acp.*
  3. 전역 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)을 받습니다. 해석 순서:
  1. 명시적 대상 인수 (/acp steer는 --session)
  2. 현재 thread binding
  3. 현재 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"를 사용하십시오.

​
관련 문서

​
최근 업데이트 메모

  • resumeSessionId로 기존 ACP 세션을 이어받을 수 있으며, 이력은 session/load로 재생됩니다.
  • /acp sessions는 현재 바인딩되었거나 요청자 세션 기준 session store를 읽습니다.