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이 필요할 때 이 흐름을 사용하세요:
- 세션 생성:
/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(세션 종료 및 바인딩 제거)
사용자를 위한 퀵 스타트
섹션 제목: “사용자를 위한 퀵 스타트”자연어 요청 예시예요:
- “여기 스레드에서 persistent Codex 세션을 시작하고 집중해줘.”
- “이걸 일회성 Claude Code ACP 세션으로 실행하고 결과를 요약해줘.”
- “이 작업에 Gemini CLI를 스레드에서 사용하고, 후속 작업도 같은 스레드에서 이어가줘.”
OpenClaw가 수행하는 작업:
runtime: "acp"를 선택해요.- 요청된 하네스 타겟(
agentId, 예:codex)을 확인해요. - 스레드 바인딩이 요청되고 현재 채널이 이를 지원하면, ACP 세션을 스레드에 바인딩해요.
- 포커스가 해제되거나, 종료되거나, 만료될 때까지 해당 스레드의 후속 메시지를 동일한 ACP 세션으로 라우팅해요.
ACP vs 서브 에이전트
섹션 제목: “ACP vs 서브 에이전트”외부 하네스 런타임이 필요할 때는 ACP를 사용하세요. OpenClaw 네이티브 위임 실행이 필요할 때는 서브 에이전트를 사용하세요.
| 영역 | ACP 세션 | 서브 에이전트 실행 |
|---|---|---|
| Runtime | ACP backend plugin (예: acpx) | OpenClaw 네이티브 서브 에이전트 런타임 |
| Session key | agent:<agentId>:acp:<uuid> | agent:<agentId>:subagent:<uuid> |
| 주요 명령어 | /acp ... | /subagents ... |
| Spawn 도구 | runtime:"acp"를 포함한 sessions_spawn | sessions_spawn (기본 런타임) |
서브 에이전트 문서도 참고해 보세요.
스레드 바인딩 세션 (채널 무관)
섹션 제목: “스레드 바인딩 세션 (채널 무관)”채널 어댑터에서 스레드 바인딩이 활성화되면 ACP 세션을 스레드에 바인딩할 수 있어요:
- OpenClaw는 스레드를 타겟 ACP 세션에 바인딩해요.
- 해당 스레드의 후속 메시지는 바인딩된 ACP 세션으로 라우팅돼요.
- ACP 출력 결과는 동일한 스레드로 다시 전달돼요.
- 포커스 해제, 종료, 아카이브, 유휴 시간 초과 또는 최대 보관 기간 만료 시 바인딩이 제거돼요.
스레드 바인딩 지원 여부는 어댑터마다 달라요. 활성화된 채널 어댑터가 스레드 바인딩을 지원하지 않으면 OpenClaw는 지원되지 않거나 사용할 수 없다는 명확한 메시지를 반환해요.
스레드 바인딩 ACP를 위한 필수 feature flags:
acp.enabled=trueacp.dispatch.enabled는 기본적으로 켜져 있어요 (ACP 디스패치를 일시 중지하려면false로 설정하세요)- 채널 어댑터 ACP thread-spawn 플래그 활성화 (어댑터별로 다름)
- Discord:
channels.discord.threadBindings.spawnAcpSessions=true - Telegram:
channels.telegram.threadBindings.spawnAcpSessions=true
- Discord:
스레드 지원 채널
섹션 제목: “스레드 지원 채널”- 세션/스레드 바인딩 기능을 제공하는 모든 채널 어댑터.
- 현재 내장된 지원:
- 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>"
- Discord 채널 또는 스레드:
bindings[].agentId는 소유권을 가진 OpenClaw 에이전트 ID예요.- 선택 사항인 ACP 오버라이드 설정은
bindings[].acp아래에 위치해요:mode(persistent또는oneshot)labelcwdbackend
에이전트별 런타임 기본값
섹션 제목: “에이전트별 런타임 기본값”agents.list[].runtime을 사용하면 에이전트마다 ACP 기본값을 한 번에 정의할 수 있어요:
agents.list[].runtime.type="acp"agents.list[].runtime.acp.agent(harness ID, 예:codex또는claude)agents.list[].runtime.acp.backendagents.list[].runtime.acp.modeagents.list[].runtime.acp.cwd
ACP 바인딩 세션에 적용되는 오버라이드 우선순위는 다음과 같아요:
bindings[].acp.*agents.list[].runtime.acp.*- 전역 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 세션 시작하기 (인터페이스)
섹션 제목: “ACP 세션 시작하기 (인터페이스)”sessions_spawn 사용하기
섹션 제목: “sessions_spawn 사용하기”에이전트 턴이나 도구 호출에서 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가 포함돼요.
- 사용 가능한 경우, 수락된 응답에는 전체 릴레이 기록을 추적할 수 있는 세션 범위의 JSONL 로그(
기존 세션 재개하기
섹션 제목: “기존 세션 재개하기”새로 시작하는 대신 이전 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 생성이 유닛 테스트 통과를 넘어 실제로 엔드투엔드로 잘 작동하는지 빠르게 확인하고 싶을 때 사용하세요.
권장 확인 단계:
- 대상 호스트에서 배포된 Gateway 버전/커밋을 확인해요.
- 배포된 소스의
src/gateway/sessions-patch.ts에 ACP 계보 수락(subagent:* or acp:* sessions)이 포함되어 있는지 확인해요. - 라이브 에이전트(예:
jpclawhq의razor(main))에 임시 ACPX 브리지 세션을 열어요. - 해당 에이전트에게 다음 파라미터로
sessions_spawn을 호출하도록 요청하세요:runtime: "acp"agentId: "codex"mode: "run"- task:
Reply with exactly LIVE-ACP-SPAWN-OK
- 에이전트가 다음과 같이 보고하는지 확인해요:
accepted=yes- 실제
childSessionKey존재 - 검증 에러 없음
- 임시 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 토픽에서 진행하는 두 번째 심화 통합 단계로 취급하세요.
Sandbox 호환성
섹션 제목: “Sandbox 호환성”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 명령어로 실행하기
섹션 제목: “/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>
자세한 내용은 Slash Commands를 참고하세요.
세션 대상 확인
섹션 제목: “세션 대상 확인”대부분의 /acp 액션은 선택적으로 세션 대상(session-key, session-id, 또는 session-label)을 인자로 받아요.
확인 순서:
- 명시적인 대상 인자 (또는
/acp steer의 경우--session)- 키(key)를 먼저 시도해요.
- 그다음 UUID 형태의 세션 ID를 시도해요.
- 마지막으로 라벨(label)을 시도해요.
- 현재 스레드 바인딩 (이 대화/스레드가 ACP 세션에 바인딩되어 있는 경우)
- 현재 요청 세션 폴백
대상을 확인할 수 없는 경우 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
- Discord:
ACP 제어 명령어 (ACP controls)
섹션 제목: “ACP 제어 명령어 (ACP controls)”사용 가능한 명령어 제품군은 다음과 같아요:
/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 명령어 쿡북
섹션 제목: “ACP 명령어 쿡북”| 명령어 | 설명 | 예시 |
|---|---|---|
/acp spawn | ACP 세션을 생성해요. 선택적으로 스레드를 바인딩할 수 있어요. | /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 지원 현황 (현재)
섹션 제목: “acpx harness 지원 현황 (현재)”현재 acpx에 내장된 harness 별칭(alias)은 다음과 같아요.
piclaudecodexopencodegeminikimi
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에서 확인할 수 있어요.
acpx 백엔드 플러그인 설정
섹션 제목: “acpx 백엔드 플러그인 설정”플러그인을 설치하고 활성화해 주세요:
openclaw plugins install acpxopenclaw config set plugins.entries.acpx.enabled true개발 중에는 로컬 워크스페이스에서 설치할 수 있어요:
openclaw plugins install ./extensions/acpx그 다음 백엔드 상태를 확인해 보세요:
/acp doctoracpx 커맨드 및 버전 설정
섹션 제목: “acpx 커맨드 및 버전 설정”기본적으로 @openclaw/acpx로 배포되는 acpx 플러그인은 플러그인 로컬에 고정된 바이너리를 사용해요:
- 커맨드 기본값은
extensions/acpx/node_modules/.bin/acpx예요. - 예상 버전 기본값은 익스텐션에 고정된 버전을 따라가요.
- 시작 시 ACP 백엔드를 즉시 ‘준비되지 않음(not-ready)’ 상태로 등록해요.
- 백그라운드 보장(ensure) 작업이
acpx --version을 확인해요. - 플러그인 로컬 바이너리가 없거나 버전이 맞지 않으면
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 플러그인은 권한 처리 방식을 제어하는 두 가지 설정 키를 제공해요.
permissionMode
섹션 제목: “permissionMode”에이전트가 프롬프트 없이 수행할 수 있는 작업 범위를 제어해요.
| 값 | 동작 |
|---|---|
approve-all | 모든 파일 쓰기와 쉘 커맨드를 자동으로 승인해요. |
approve-reads | 읽기 작업만 자동 승인해요. 쓰기와 실행은 프롬프트가 필요해요. |
deny-all | 모든 권한 요청을 거부해요. |
nonInteractivePermissions
섹션 제목: “nonInteractivePermissions”권한 프롬프트를 보여줘야 하지만 대화형 TTY를 사용할 수 없을 때(ACP 세션은 항상 이 경우에 해당해요) 어떻게 할지 제어해요.
| 값 | 동작 |
|---|---|
fail | AcpRuntimeError와 함께 세션을 중단해요. (기본값) |
deny | 알림 없이 권한을 거부하고 세션을 계속 진행해요 (기능 제한적 유지). |
설정 방법
섹션 제목: “설정 방법”플러그인 설정을 통해 적용할 수 있어요:
openclaw config set plugins.entries.acpx.config.permissionMode approve-allopenclaw 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 mode | permissionMode가 비대화형 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 Expert
아직 막혀 있나요?
이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.