콘텐츠로 이동
이 페이지는 더 이상 업데이트되지 않습니다. 최신 내용은 OpenClaw 공식 문서에서 확인하세요 →

OpenClaw ACP 에이전트 설정: 외부 코딩 도구 6단계 연결 가이드

Agent Client Protocol (ACP) 세션은 OpenClaw가 ACP backend plugin을 통해 외부 코딩 하네스(예: Pi, Claude Code, Codex, OpenCode, Gemini CLI)를 실행할 수 있게 해줘요.

일상적인 언어로 “Codex에서 이걸 실행해줘” 또는 “스레드에서 Claude Code를 시작해줘”라고 요청하면, OpenClaw는 이 요청을 네이티브 서브 에이전트 런타임이 아닌 ACP runtime으로 라우팅해요.

실용적인 /acp runbook이 필요할 때 이 흐름을 사용하세요:

  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 (세션 종료 및 바인딩 제거)

자연어 요청 예시예요:

  • “여기 스레드에서 persistent Codex 세션을 시작하고 집중해줘.”
  • “이걸 일회성 Claude Code ACP 세션으로 실행하고 결과를 요약해줘.”
  • “이 작업에 Gemini CLI를 스레드에서 사용하고, 후속 작업도 같은 스레드에서 이어가줘.”

OpenClaw가 수행하는 작업:

  1. runtime: "acp"를 선택해요.
  2. 요청된 하네스 타겟(agentId, 예: codex)을 확인해요.
  3. 스레드 바인딩이 요청되고 현재 채널이 이를 지원하면, ACP 세션을 스레드에 바인딩해요.
  4. 포커스가 해제되거나, 종료되거나, 만료될 때까지 해당 스레드의 후속 메시지를 동일한 ACP 세션으로 라우팅해요.

외부 하네스 런타임이 필요할 때는 ACP를 사용하세요. OpenClaw 네이티브 위임 실행이 필요할 때는 서브 에이전트를 사용하세요.

영역ACP 세션서브 에이전트 실행
RuntimeACP backend plugin (예: acpx)OpenClaw 네이티브 서브 에이전트 런타임
Session keyagent:<agentId>:acp:<uuid>agent:<agentId>:subagent:<uuid>
주요 명령어/acp .../subagents ...
Spawn 도구runtime:"acp"를 포함한 sessions_spawnsessions_spawn (기본 런타임)

서브 에이전트 문서도 참고해 보세요.

스레드 바인딩 세션 (채널 무관)

섹션 제목: “스레드 바인딩 세션 (채널 무관)”

채널 어댑터에서 스레드 바인딩이 활성화되면 ACP 세션을 스레드에 바인딩할 수 있어요:

  • OpenClaw는 스레드를 타겟 ACP 세션에 바인딩해요.
  • 해당 스레드의 후속 메시지는 바인딩된 ACP 세션으로 라우팅돼요.
  • ACP 출력 결과는 동일한 스레드로 다시 전달돼요.
  • 포커스 해제, 종료, 아카이브, 유휴 시간 초과 또는 최대 보관 기간 만료 시 바인딩이 제거돼요.

스레드 바인딩 지원 여부는 어댑터마다 달라요. 활성화된 채널 어댑터가 스레드 바인딩을 지원하지 않으면 OpenClaw는 지원되지 않거나 사용할 수 없다는 명확한 메시지를 반환해요.

스레드 바인딩 ACP를 위한 필수 feature flags:

  • acp.enabled=true
  • acp.dispatch.enabled는 기본적으로 켜져 있어요 (ACP 디스패치를 일시 중지하려면 false로 설정하세요)
  • 채널 어댑터 ACP thread-spawn 플래그 활성화 (어댑터별로 다름)
    • 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 (harness 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 세션을 시작하려면 runtime: "acp"를 사용하세요.

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

새로 시작하는 대신 이전 ACP 세션을 계속하려면 resumeSessionId를 사용하세요. 에이전트가 session/load를 통해 대화 기록을 재생하므로, 이전 맥락을 그대로 이어받아 작업할 수 있어요.

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

주요 사용 사례:

  • 노트북에서 하던 Codex 세션을 휴대폰으로 넘겨서 에이전트에게 중단된 부분부터 계속하라고 지시할 때
  • CLI에서 대화형으로 시작한 코딩 세션을 에이전트를 통해 백그라운드에서 계속 진행할 때
  • Gateway 재시작이나 유휴 시간 초과로 중단된 작업을 다시 시작할 때

참고 사항:

  • resumeSessionId는 runtime: "acp"를 요구하며, sub-agent 런타임과 함께 사용하면 에러를 반환해요.
  • resumeSessionId는 업스트림 ACP 대화 기록을 복구해요. thread와 mode는 새로 생성하는 OpenClaw 세션에 정상적으로 적용되므로, mode: "session"은 여전히 thread: true가 필요해요.
  • 대상 에이전트가 session/load를 지원해야 해요 (Codex와 Claude Code는 지원해요).
  • 세션 ID를 찾을 수 없으면 생성이 실패하고 명확한 에러가 발생해요. 자동으로 새 세션으로 넘어가지 않아요.

운영자 스모크 테스트 (Smoke test)

섹션 제목: “운영자 스모크 테스트 (Smoke test)”

Gateway 배포 후 ACP 생성이 유닛 테스트 통과를 넘어 실제로 엔드투엔드로 잘 작동하는지 빠르게 확인하고 싶을 때 사용하세요.

권장 확인 단계:

  1. 대상 호스트에서 배포된 Gateway 버전/커밋을 확인해요.
  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 Sandbox 내부가 아니라 호스트 런타임에서 실행돼요.

현재 제한 사항:

  • 요청 세션이 샌드박스 처리된 경우, 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.
  • runtime: "acp"를 사용하는 sessions_spawn은 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 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>

자세한 내용은 Slash Commands를 참고하세요.

대부분의 /acp 액션은 선택적으로 세션 대상(session-key, session-id, 또는 session-label)을 인자로 받아요.

확인 순서:

  1. 명시적인 대상 인자 (또는 /acp steer의 경우 --session)
    • 키(key)를 먼저 시도해요.
    • 그다음 UUID 형태의 세션 ID를 시도해요.
    • 마지막으로 라벨(label)을 시도해요.
  2. 현재 스레드 바인딩 (이 대화/스레드가 ACP 세션에 바인딩되어 있는 경우)
  3. 현재 요청 세션 폴백

대상을 확인할 수 없는 경우 OpenClaw는 명확한 에러(Unable to resolve session target: ...)를 반환해요.

스레드 생성 모드 (Spawn thread modes)

섹션 제목: “스레드 생성 모드 (Spawn thread modes)”

/acp spawn 명령어는 --thread auto|here|off 옵션을 지원해요.

모드동작 방식
auto활성화된 스레드 내에서는 해당 스레드에 바인딩해요. 스레드 외부인 경우, 지원되는 환경이라면 하위 스레드를 생성하거나 바인딩해요.
here현재 활성화된 스레드가 반드시 필요하며, 스레드 내부가 아닐 경우 실패해요.
off바인딩을 사용하지 않아요. 세션이 바인딩되지 않은 상태로 시작돼요.

참고 사항:

  • 스레드 바인딩을 지원하지 않는 환경에서는 기본 동작이 사실상 off와 같아요.
  • 스레드 바인딩 방식의 spawn을 사용하려면 채널 정책(channel policy) 지원이 필요해요:
    • Discord: channels.discord.threadBindings.spawnAcpSessions=true
    • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

사용 가능한 명령어 제품군은 다음과 같아요:

  • /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를 사용하면 현재 적용 중인 런타임 옵션을 확인할 수 있어요. 또한 가능한 경우 런타임 레벨과 백엔드 레벨의 세션 식별자(identifier)를 모두 보여줘요.

일부 제어 기능은 백엔드 기능에 따라 달라질 수 있어요. 만약 백엔드에서 특정 제어 기능을 지원하지 않는다면, OpenClaw는 지원되지 않는 제어 오류(unsupported-control error)를 명확하게 반환해요.

명령어설명예시
/acp spawnACP 세션을 생성해요. 선택적으로 스레드를 바인딩할 수 있어요./acp spawn codex --mode persistent --thread auto --cwd /repo
/acp cancel대상 세션에서 진행 중인 턴(turn)을 취소해요./acp cancel agent:codex:acp:<uuid>
/acp steer실행 중인 세션에 조종(steer) 지침을 보내요./acp steer --session support inbox prioritize failing tests
/acp close세션을 닫고 바인딩된 스레드 대상을 해제해요./acp close
/acp status백엔드, 모드, 상태, 런타임 옵션, 기능을 보여줘요./acp status
/acp set-mode대상 세션의 런타임 모드를 설정해요./acp set-mode plan
/acp set일반적인 런타임 설정 옵션을 입력해요./acp set model openai/gpt-5.2
/acp cwd런타임 작업 디렉토리(cwd) 오버라이드를 설정해요./acp cwd /Users/user/Projects/repo
/acp permissions승인 정책 프로필을 설정해요./acp permissions strict
/acp timeout런타임 타임아웃(초 단위)을 설정해요./acp timeout 120
/acp model런타임 모델 오버라이드를 설정해요./acp model anthropic/claude-opus-4-5
/acp reset-options세션 런타임 옵션 오버라이드를 제거해요./acp reset-options
/acp sessions저장소에서 최근 ACP 세션 목록을 나열해요./acp sessions
/acp doctor백엔드 상태, 기능, 조치 가능한 해결 방법을 확인해요./acp doctor
/acp install확정적인 설치 및 활성화 단계를 출력해요./acp install

/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에 내장된 harness 별칭(alias)은 다음과 같아요.

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

OpenClaw에서 acpx 백엔드를 사용할 때, acpx 설정에 별도의 커스텀 에이전트 별칭을 정의하지 않았다면 agentId 값으로 이 이름들을 사용하는 것이 좋아요.

acpx CLI를 직접 사용할 때는 --agent <command>를 통해 임의의 어댑터를 지정할 수도 있어요. 하지만 이 방식은 acpx CLI 자체 기능이며, 일반적인 OpenClaw agentId 경로와는 다르다는 점을 기억해 주세요.

핵심 ACP 기본 설정이에요.

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

스레드 바인딩(Thread binding) 설정은 채널 어댑터마다 달라요. Discord를 예로 들면 다음과 같아요.

{
session: {
threadBindings: {
enabled: true,
idleHours: 24,
maxAgeHours: 0,
},
},
channels: {
discord: {
threadBindings: {
enabled: true,
spawnAcpSessions: true,
},
},
},
}

만약 스레드 바인딩된 ACP 생성이 제대로 작동하지 않는다면, 먼저 어댑터의 기능 플래그(feature flag)를 확인해 보세요.

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

자세한 내용은 Configuration Reference에서 확인할 수 있어요.

플러그인을 설치하고 활성화해 주세요:

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

개발 중에는 로컬 워크스페이스에서 설치할 수 있어요:

Terminal window
openclaw plugins install ./extensions/acpx

그 다음 백엔드 상태를 확인해 보세요:

/acp doctor

기본적으로 @openclaw/acpx로 배포되는 acpx 플러그인은 플러그인 로컬에 고정된 바이너리를 사용해요:

  1. 커맨드 기본값은 extensions/acpx/node_modules/.bin/acpx예요.
  2. 예상 버전 기본값은 익스텐션에 고정된 버전을 따라가요.
  3. 시작 시 ACP 백엔드를 즉시 ‘준비되지 않음(not-ready)’ 상태로 등록해요.
  4. 백그라운드 보장(ensure) 작업이 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 시작 프로세스는 중단되지 않아요.

Plugins 문서를 참고해 보세요.

ACP 세션은 비대화형(non-interactive)으로 실행돼요. 즉, 파일 쓰기나 쉘 실행 권한을 묻는 프롬프트가 떠도 이를 승인하거나 거부할 TTY가 없다는 뜻이죠. acpx 플러그인은 권한 처리 방식을 제어하는 두 가지 설정 키를 제공해요.

에이전트가 프롬프트 없이 수행할 수 있는 작업 범위를 제어해요.

값동작
approve-all모든 파일 쓰기와 쉘 커맨드를 자동으로 승인해요.
approve-reads읽기 작업만 자동 승인해요. 쓰기와 실행은 프롬프트가 필요해요.
deny-all모든 권한 요청을 거부해요.

권한 프롬프트를 보여줘야 하지만 대화형 TTY를 사용할 수 없을 때(ACP 세션은 항상 이 경우에 해당해요) 어떻게 할지 제어해요.

값동작
failAcpRuntimeError와 함께 세션을 중단해요. (기본값)
deny알림 없이 권한을 거부하고 세션을 계속 진행해요 (기능 제한적 유지).

플러그인 설정을 통해 적용할 수 있어요:

Terminal window
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

설정값을 바꾼 후에는 Gateway를 다시 시작해 주세요.

중요: 현재 OpenClaw의 기본값은 permissionMode=approve-reads와 nonInteractivePermissions=fail이에요. 비대화형 ACP 세션에서 권한 프롬프트를 발생시키는 쓰기나 실행 작업은 AcpRuntimeError: Permission prompt unavailable in non-interactive mode 오류와 함께 실패할 수 있어요.

권한을 제한해야 한다면 nonInteractivePermissions를 deny로 설정하세요. 그러면 세션이 멈추지 않고 권한이 필요한 기능만 제한된 채로 계속 실행돼요.

증상예상 원인해결 방법
ACP runtime backend is not configured백엔드 플러그인이 없거나 비활성화되어 있어요.백엔드 플러그인을 설치하고 활성화한 뒤 /acp doctor를 실행하세요.
ACP is disabled by policy (acp.enabled=false)ACP가 전역적으로 비활성화되어 있어요.acp.enabled=true로 설정하세요.
ACP dispatch is disabled by policy (acp.dispatch.enabled=false)일반 스레드 메시지에서의 디스패치가 비활성화되어 있어요.acp.dispatch.enabled=true로 설정하세요.
ACP agent "<id>" is not allowed by policy에이전트가 허용 목록(allowlist)에 없어요.허용된 agentId를 사용하거나 acp.allowedAgents를 업데이트하세요.
Unable to resolve session target: ...잘못된 key/id/label 토큰이에요./acp sessions를 실행해 정확한 key/label을 복사해서 다시 시도하세요.
--thread here requires running /acp spawn inside an active ... thread스레드 컨텍스트 밖에서 --thread here를 사용했어요.대상 스레드로 이동하거나 --thread auto/off를 사용하세요.
Only <user-id> can rebind this thread.다른 사용자가 스레드 바인딩 권한을 가지고 있어요.소유자 계정으로 다시 바인딩하거나 다른 스레드를 사용하세요.
Thread bindings are unavailable for <channel>.어댑터가 스레드 바인딩 기능을 지원하지 않아요.--thread off를 사용하거나 지원되는 어댑터/채널로 이동하세요.
Sandboxed sessions cannot spawn ACP sessions ...ACP 런타임은 호스트 측에 있고, 요청 세션은 샌드박스 상태예요.샌드박스 세션에서 runtime="subagent"를 사용하거나, 샌드박스가 아닌 세션에서 ACP spawn을 실행하세요.
sessions_spawn sandbox="require" is unsupported for runtime="acp" ...ACP 런타임에 sandbox="require"를 요청했어요.샌드박스가 꼭 필요하면 runtime="subagent"를 사용하고, ACP를 쓸 때는 샌드박스가 아닌 세션에서 sandbox="inherit"을 사용하세요.
바인딩된 세션에 ACP 메타데이터가 없음ACP 세션 메타데이터가 오래되었거나 삭제되었어요./acp spawn으로 다시 생성한 뒤 스레드를 다시 바인딩하거나 포커스하세요.
AcpRuntimeError: Permission prompt unavailable in non-interactive modepermissionMode가 비대화형 ACP 세션의 쓰기/실행을 차단하고 있어요.plugins.entries.acpx.config.permissionMode를 approve-all로 설정하고 Gateway를 재시작하세요. 권한 설정 섹션을 참고하세요.
ACP 세션이 출력 내용 거의 없이 일찍 종료됨permissionMode나 nonInteractivePermissions에 의해 권한 프롬프트가 차단되었어요.Gateway 로그에서 AcpRuntimeError를 확인하세요. 모든 권한을 허용하려면 permissionMode=approve-all로, 기능 제한 상태로 유지하려면 nonInteractivePermissions=deny로 설정하세요.
ACP 세션이 작업을 마친 후에도 무한히 대기함Harness 프로세스는 끝났지만 ACP 세션이 완료 보고를 하지 않았어요.ps aux | grep acpx로 모니터링하고, 멈춰있는 프로세스를 수동으로 종료하세요.
OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.