실제 인프라(Azure 배포, Terraform 계획, 네트워크 프로비저닝)에 대해 AI 에이전트를 실행해 본 적이 있다면 벽에 부딪힌 적이 있을 것입니다. 에이전트가 장기 실행되는 CLI 명령을 발사하면 전체 메인 루프가 멈춥니다. 응답도, 상태 업데이트도, 취소할 방법도 없습니다. 그 네트워크 호출이 돌아오기를(또는 돌아오지 않기를) 기다리며 그저 침묵뿐입니다.
이것이 프로덕션 AI 에이전트 워크플로우에서 가장 큰 신뢰성 문제이며, 제가 OpenClaw 내에서 Agent Client Protocol (ACP)을 강하게 밀어붙이는 이유입니다. ACP가 느린 작업을 마법처럼 빠르게 만들지는 않습니다. 대신 에이전트 전체를 끌고 가지 못하도록 격리합니다.
작동 방식과 설정 방법을 설명하겠습니다.
ACP가 실제로 무엇인가
Agent Client Protocol은 코딩 에이전트가 서로 다른 클라이언트(IDE, 편집기, 오케스트레이터 등) 간에 상호 운용되도록 만드는 표준입니다. 핵심적으로 stdio를 통한 JSON-RPC를 사용하여 호스트 애플리케이션과 코딩 에이전트 간의 통신을 표준화합니다. 로컬 에이전트는 서브프로세스로 실행되어 파이프를 통해 다시 통신합니다.
이것이 사양 수준의 설명입니다. 우리에게 중요한 것은 이렇습니다. ACP는 OpenClaw가 외부 코딩 하네스(Claude Code, Codex, Gemini CLI)를 메인 에이전트 루프에서 인라인으로 모든 작업을 수행하는 대신 감독되는 자식 프로세스로 실행할 수 있는 방법을 제공합니다.
OpenClaw는 두 방향으로 ACP를 사용합니다.
- OpenClaw 내부의 ACP 세션 —
acpx백엔드 플러그인을 통해 외부 하네스를 실행합니다. OpenClaw가 프로세스를 감독하고, 수명 주기를 관리하며, 상황이 잘못되면 종료할 수 있습니다. - OpenClaw ACP 브리지(
openclaw acp) — IDE가 프롬프트를 OpenClaw Gateway 세션으로 전달할 수 있도록 stdio를 통해 ACP를 말하는 CLI 명령입니다.
이 글에서는 첫 번째 사례를 다룹니다.
핵심 문제: 에이전트 루프는 단일 스레드입니다
프로덕션에서 제가 계속 보는 실패 모드입니다. OpenClaw 메인 에이전트 턴이 장기 실행되는 Azure 네트워킹 호출(예: VNet 피어링 프로비저닝 또는 Terraform apply 대기)을 직접 호출합니다. 그 에이전트 루프는 직렬화되어 있습니다. 한 번에 하나의 작업입니다. Azure API가 응답하기를 기다리는 동안 전체 에이전트가 응답하지 않습니다.
채팅 응답도 없습니다. 다른 작업을 확인할 수도 없습니다. 취소 버튼도 없습니다. API 호출이 10분 동안 중단되면 에이전트도 10분 동안 중단됩니다. 영원히 중단되면(그리고 Azure 네트워킹 호출은 절대 영원히 중단될 수 있습니다) 에이전트도 영원히 중단됩니다.
단순히 타임아웃을 늘리고 싶은 유혹이 있습니다. 그것은 해결책이 아니라 기한이 있는 기도입니다.
ACP가 이를 어떻게 해결하는가
사람들이 “ACP가 OpenClaw의 중단을 방지한다"고 말할 때, 그 의미는 위험하고 느리고 실패하기 쉬운 작업을 인라인으로 수행하는 대신 OpenClaw가 감독하는 외부 하네스 프로세스에서 실행한다는 뜻입니다.
acpx 백엔드는 작업을 감독되는 자식 프로세스로 스폰합니다. 런타임이 전송, 큐잉, 취소, 재연결을 처리합니다. Claude Code가 절대 돌아오지 않을 Azure 호출을 기다리며 멈추더라도, 그 멈춘 작업은 다른 프로세스에 있습니다. OpenClaw의 메인 루프는 응답을 유지합니다. 다음을 수행할 수 있습니다.
- 멈춘 세션 취소
- 세션을 닫고 TTL 리퍼가 정리하도록 두기
- 다른 작업을 수행하기 위해 새 세션 스폰
- 백그라운드 작업이 실행되는 동안 에이전트와 계속 채팅
이것은 AI 에이전트 오케스트레이션에 적용된 프로세스 격리입니다. 새로운 컴퓨터 과학이 아닙니다. 웹 서버를 워커 프로세스 없이 단일 스레드 이벤트 루프로 실행하지 않는 것과 같은 이유입니다. 하지만 대부분의 에이전트 프레임워크에서는 놀라울 정도로 부족합니다.
설정하기
사전 요구 사항
Claude Code는 독립적으로 설치되어야 합니다. Windows에서는 PowerShell 설치 스크립트를 사용하고, Linux/macOS에서는 curl을 사용하세요. 첫 실행 시 인증을 요청합니다. ACP에 연결하기 전에 해결해 두세요.
acpx 플러그인 설치
openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
모든 것이 제대로 연결되었는지 확인하세요.
/acp doctor
이것은 백엔드 상태 검사를 실행합니다. 실패하면 일반적으로 Claude Code 설치 누락 또는 인증 문제입니다.
ACP 구성
주요 구성 필드:
openclaw config set acp.enabled true
openclaw config set acp.backend "acpx"
openclaw config set acp.defaultAgent "claude-code"
openclaw config set acp.maxConcurrentSessions 8
acp.allowedAgents를 설정하여 사용 가능한 하네스를 제한하고, runtime.ttlMinutes를 설정하여 유용성이 만료된 세션을 자동 수거할 수도 있습니다.
권한 처리 (이것이 문제가 됩니다)
ACP 세션은 비대화형으로 실행됩니다. TTY가 없습니다. 즉, 기본 권한 모덜(읽기 승인, 쓰기 실패)은 하네스가 파일을 쓰거나 명령을 실행하려는 순간 AcpRuntimeError를 던집니다.
보안 태세에 맞게 permissionMode와 nonInteractivePermissions를 구성해야 합니다. 인프라 자동화의 경우 일반적으로 쓰기 및 실행 권한을 활성화해야 합니다. 이것은 의도적으로 결정하세요. ACP 세션은 샌드박스가 아닌 호스트 런타임에서 실행됩니다.
일상적인 사용
슬래시 명령
운영자 워크플로우는 간단합니다.
/acp spawn— 새 ACP 세션 시작/acp status— 실행 중인 세션 확인/acp timeout <seconds>— 세션 타임아웃 설정/acp steer— 실행 중인 세션에 추가 지시 전송/acp cancel— 멈춘 세션 종료/acp close— 정상 종료
프로그래밍 방식 스폰
자동화된 워크플로우의 경우 runtime: "acp"와 함께 sessions_spawn을 사용하세요. agentId 매개변수가 사용할 하네스를 선택하고, mode는 run(일회성, 실행 후 반환) 또는 session(지속적, 후속 작업을 위해 하네스를 유지) 중 하나일 수 있습니다.
스레드 바인딩도 가능합니다. Discord 스레드와 Telegram 포럼 주제를 특정 ACP 세션에 연결할 수 있으므로, 팀이 작업별로 격리된 대화 컨텍스트를 얻게 됩니다.
논블로킹 패턴
ACP 세션은 더 넓은 도구 키트의 한 도구입니다. 다음은 에이전트 워크플로우를 응답성 있게 유지하기 위해 제가 사용하는 네 가지 패턴입니다.
옵션 A: Exec 백그라운딩. exec 도구는 timeout 매개변수(기본 1800초)와 yieldMs를 통한 자동 백그라운딩을 지원합니다. 명령을 발사하고, 몇 초 후 백그라운드로 전환한 다음 결과를 폴링하세요. 알려진 기간의 작업에 간단하고 효과적입니다.
옵션 B: ACP 세션. 도구 사용, 파일 작업, 의사결정이 포함된 복잡한 다단계 작업(단일 셸 명령이 아닌)의 경우 ACP 세션이 완전한 하네스 격리를 제공합니다. 하네스가 메인 루프에 영향을 주지 않고 생각하고, 행동하고, 멈출 수 있습니다.
옵션 C: Cron 조정. OpenClaw cron 작업을 설정하여 인프라 상태를 주기적으로 확인하세요. 배포가 완료되기를 기다리는 대신 몇 분마다 조정 확인을 예약하세요. 에이전트가 깨어나서 상태를 확인하고, 행동하거나 다시 잠듭니다.
옵션 D: 웹훅. 이벤트 기반 워크플로우의 경우 외부 cron 또는 인프라 콜백이 OpenClaw의 웹훅 엔드포인트(/hooks/agent)를 치도록 합니다. Terraform apply가 완료되거나 Azure 배포가 끝나면 웹훅을 발사하여 에이전트를 깨우세요. 폴링도 중단도 없습니다.
실제로는 네 가지를 모두 결합합니다. 무거운 작업은 ACP 세션, 빠른 명령은 exec 백그라운딩, 조정은 cron, 상태 변경 알림은 웹훅입니다.
문제 해결
권한 실패
세션 스폰 직후 AcpRuntimeError가 보이면 거의 항상 비대화형 권한 기본값입니다. permissionMode와 nonInteractivePermissions 설정을 확인하세요.
좀비 세션
작업은 완료했지만 제대로 닫히지 않은 세션은 동시성 슬롯을 소모합니다. /acp status로 모니터링하고 runtime.ttlMinutes를 설정하여 오래된 세션을 자동 수거하세요. acp.maxConcurrentSessions 한도에 도달하면 먼저 좀비를 확인하세요.
중단 유형 구분
모든 중단이 같은 것은 아니며, 해결 방법은 다루는 유형에 따라 다릅니다.
- 메인 루프가 셸에서 차단 — 에이전트 자체가 인라인 exec 호출을 기다리며 멈춤. 이것이 ACP가 해결하는 문제입니다. 작업을 세션으로 이동하세요.
- 완료 후 ACP 세션이 멈춤 — 하네스는 완료했지만 세션이 깔끔하게 닫히지 않음.
/acp close를 사용하거나 TTL이 처리하도록 두세요. - 네트워크에서 하네스가 진정으로 멈춤 — Claude Code 자체가 외부 API를 기다리며 멈춤.
/acp cancel로 세션을 종료한 다음 근본적인 네트워크 문제를 조사하세요.
Claude Code 설치 및 인증
생각보다 더 자주 사람들을 당황하게 합니다. Claude Code는 실제 의존성입니다. 설치되지 않았거나, 인증되지 않았거나, 인증 토큰이 만료된 경우 ACP 세션은 스폰 시점에 실패합니다. 먼저 /acp doctor를 실행하세요. 항상.
보안 고려 사항
ACP 세션은 샌드박스가 아닌 호스트 런타임에서 실행됩니다. 이것은 의도된 것입니다. 실제 인프라 도구에 액세스해야 하기 때문입니다. 하지만 보안 경계를 생각해야 함을 의미합니다.
웹훅의 경우, 엔드포인트를 루프백 또는 Tailnet/프록시 뒤에 두세요. 웹훅 인증에는 전용 토큰을 사용하고, 외부 호출자가 임의의 작업을 스폰할 수 없도록 에이전트 및 세션 라우팅을 제한하세요.
결론
에이전트 중단은 사소한 불편함이 아닙니다. AI 자동화를 프로덕션 인프라 작업에 신뢰할 수 없게 만드는 신뢰성 문제입니다. ACP는 가장 중단 가능성이 높은 작업에 프로세스 격리, 수명 주기 제어, 타임아웃 관리를 제공합니다.
설정이 복잡하지 않습니다. 마법이 아닙니다. 에이전트 오케스트레이션에 적용된 좋은 엔지니어링 관행입니다. 하나의 느린 작업이 전체 시스템을 끌고 가지 못하게 하세요.
인프라 자동화를 위한 AI 에이전트 워크플로우를 구축 중이고 신뢰성 문제에 직면한 경우, 이야기해 봅시다. 이것이 바로 Big Hat Group이 수행하는 프로덕션 강화 작업의 종류입니다. OpenClaw 컨설팅에서 확인하세요.