ACP 에이전트

• plugins.allow가 설정되어 있으면 제한적인 Plugin 목록으로 작동하므로 설치된 ACP 백엔드가 의도적으로 차단되지 않으려면 반드시 acpx를 포함해야 합니다(/acp doctor는 허용 목록에 항목이 없다고 보고합니다).
• Codex ACP 어댑터는 acpx Plugin과 함께 제공되며 가능한 경우 로컬에서 실행됩니다.
• Codex ACP는 격리된 CODEX_HOME으로 실행됩니다. OpenClaw는 신뢰하는 프로젝트의 신뢰 항목과 안전한 모델/제공자 라우팅 설정(model, model_provider, model_reasoning_effort, sandbox_mode 및 안전한 model_providers.<name> 필드)을 호스트 Codex 구성에서 복사합니다. 인증, 알림 및 훅은 호스트 구성에만 유지됩니다.
• 다른 대상 하네스 어댑터는 최초 사용 시 필요에 따라 npx로 가져올 수 있습니다.
• 해당 하네스의 공급업체 인증이 호스트에 이미 존재해야 합니다.
• 호스트에서 npm 또는 네트워크에 접근할 수 없으면 캐시를 미리 채우거나 다른 방법으로 어댑터를 설치하기 전까지 최초 실행 시 어댑터 가져오기가 실패합니다.

ACP는 실제 외부 하네스 프로세스를 실행합니다. OpenClaw는 라우팅, 백그라운드 작업 상태, 전달, 바인딩 및 정책을 담당하고, 하네스는 제공자 로그인, 모델 카탈로그, 파일 시스템 동작 및 네이티브 도구를 담당합니다.

OpenClaw의 문제라고 판단하기 전에 다음을 확인하세요.

• /acp doctor가 활성화된 정상 상태의 백엔드를 보고합니다.
• 해당 허용 목록이 설정되어 있다면 대상 ID가 acp.allowedAgents에서 허용됩니다.
• Gateway 호스트에서 하네스 명령을 시작할 수 있습니다.
• 해당 하네스의 제공자 인증이 존재합니다(claude, codex, gemini, opencode, droid 등).
• 선택한 모델이 해당 하네스에 존재합니다. 모델 ID는 하네스 간에 호환되지 않습니다.
• 요청한 cwd가 존재하고 접근 가능해야 합니다. 그렇지 않으면 cwd를 생략하여 백엔드가 기본값을 사용하도록 하세요.
• 권한 모드가 작업에 적합합니다. 비대화형 세션에서는 네이티브 권한 프롬프트를 클릭할 수 없으므로 쓰기/실행이 많은 코딩 작업에는 일반적으로 사용자 개입 없이 진행할 수 있는 ACPX 권한 프로필이 필요합니다.

• 세션 생성은 ACP 런타임 세션을 생성하거나 재개하고 OpenClaw 세션 저장소에 ACP 메타데이터를 기록하며, 실행이 상위 작업 소유인 경우 백그라운드 작업을 생성할 수 있습니다.
• 상위 작업 소유 ACP 세션은 런타임 세션이 영구적이어도 백그라운드 작업으로 처리됩니다. 완료 및 화면 간 전달은 일반적인 사용자 대상 채팅 세션처럼 작동하는 대신 상위 작업 알림기를 통해 처리됩니다.
• 작업 유지 관리는 종료되었거나 분리된 상위 작업 소유 일회성 ACP 세션을 닫습니다. 활성 대화 바인딩이 유지되는 동안에는 영구 ACP 세션이 보존됩니다. 활성 바인딩이 없는 오래된 영구 세션은 소유 작업이 완료되었거나 작업 기록이 사라진 후 자동으로 재개되지 않도록 닫힙니다.
• 바인딩된 후속 메시지는 바인딩이 닫히거나, 포커스가 해제되거나, 재설정되거나, 만료될 때까지 ACP 세션으로 직접 전달됩니다.
• Gateway 명령은 로컬에서 처리됩니다. /acp ..., /status, /unfocus는 바인딩된 ACP 하네스에 일반 프롬프트 텍스트로 전송되지 않습니다.
• 백엔드가 취소를 지원하면 cancel은 활성 턴을 중단합니다. 바인딩 또는 세션 메타데이터는 삭제하지 않습니다.
• close는 OpenClaw 관점에서 ACP 세션을 종료하고 바인딩을 제거합니다. 하네스가 재개를 지원하는 경우 자체 업스트림 기록은 계속 유지할 수 있습니다.
• acpx Plugin은 close 후 OpenClaw 소유 래퍼 및 어댑터 프로세스 트리를 정리하고, Gateway 시작 중에 오래된 OpenClaw 소유 ACPX 고아 프로세스를 수거합니다.
• 유휴 런타임 워커는 acp.runtime.ttlMinutes 이후 정리 대상이 됩니다. 저장된 세션 메타데이터는 /acp sessions에서 계속 사용할 수 있습니다.

다음 자연어 트리거는 활성화된 경우 네이티브 Codex Plugin으로 라우팅되어야 합니다.

• "이 Discord 채널을 Codex에 바인딩하세요."
• "이 채팅을 Codex 스레드 <id>에 연결하세요."
• "Codex 스레드를 표시한 다음 이 스레드를 바인딩하세요."

네이티브 Codex 대화 바인딩은 기본 채팅 제어 경로입니다. OpenClaw 동적 도구는 계속 OpenClaw를 통해 실행되지만, 셸/apply-patch 같은 Codex 네이티브 도구는 Codex 내부에서 실행됩니다. Codex 네이티브 도구 이벤트의 경우 OpenClaw는 턴별 네이티브 훅 릴레이를 주입하여 Plugin 훅이 before_tool_call을 차단하고, after_tool_call을 관찰하며, Codex PermissionRequest 이벤트를 OpenClaw 승인을 통해 라우팅할 수 있게 합니다. Codex Stop 훅은 OpenClaw before_agent_finalize로 릴레이되며, 여기서 Plugin은 Codex가 답변을 확정하기 전에 모델 패스를 한 번 더 요청할 수 있습니다. 이 릴레이는 의도적으로 보수적으로 동작합니다. Codex 네이티브 도구 인수를 변경하거나 Codex 스레드 레코드를 다시 작성하지 않습니다. ACP 런타임/세션 모델을 원하는 경우에만 명시적 ACP를 사용하세요. 임베디드 Codex 지원 범위는 Codex 하네스 v1 지원 계약에 문서화되어 있습니다.

• 레거시 Codex 모델 참조 - doctor가 복구하는 레거시 Codex OAuth/구독 모델 경로.
• openai/* - OpenAI 에이전트 턴을 위한 네이티브 Codex app-server 임베디드 런타임.
• /codex ... - 네이티브 Codex 대화 제어.
• /acp ... 또는 runtime: "acp" - 명시적 ACP/acpx 제어.

ACP 런타임으로 라우팅되어야 하는 트리거:

• "이 작업을 일회성 Claude Code ACP 세션으로 실행하고 결과를 요약하세요."
• "이 작업에는 스레드에서 Gemini CLI를 사용하고, 이후 후속 작업도 같은 스레드에서 계속하세요."
• "백그라운드 스레드에서 ACP를 통해 Codex를 실행하세요."

OpenClaw는 runtime: "acp"를 선택하고 하네스 agentId를 확인하며, 지원되는 경우 현재 대화 또는 스레드에 바인딩하고, 닫히거나 만료될 때까지 후속 요청을 해당 세션으로 라우팅합니다. Codex는 ACP/acpx가 명시되었거나 요청한 작업에 네이티브 Codex Plugin을 사용할 수 없는 경우에만 이 경로를 따릅니다.

sessions_spawn의 경우 ACP가 활성화되어 있고, 요청자가 샌드박스에 격리되지 않았으며, ACP 런타임 백엔드가 로드된 경우에만 runtime: "acp"가 제공됩니다. acp.dispatch.enabled=false는 자동 ACP 스레드 디스패치를 일시 중지하지만 명시적 sessions_spawn({ runtime: "acp" }) 호출을 숨기거나 차단하지 않습니다. 이는 codex, claude, droid, gemini, opencode 같은 ACP 하네스 ID를 대상으로 합니다. 해당 항목이 agents.list[].runtime.type="acp"로 명시적으로 구성되지 않았다면 agents_list의 일반 OpenClaw 구성 에이전트 ID를 전달하지 마세요. 대신 기본 하위 에이전트 런타임을 사용하세요. OpenClaw 에이전트가 runtime.type="acp"로 구성된 경우 OpenClaw는 runtime.acp.agent를 기본 하네스 ID로 사용합니다.

• --bind here와 --thread ...는 함께 사용할 수 없습니다.
• --bind here는 현재 대화 바인딩을 지원한다고 알리는 채널에서만 작동합니다. 그 외에는 OpenClaw가 명확한 미지원 메시지를 반환합니다. 바인딩은 Gateway 재시작 후에도 유지됩니다.
• Discord에서 spawnSessions는 --thread auto|here의 하위 스레드 생성을 제어하지만 --bind here는 제어하지 않습니다.
• --cwd 없이 다른 ACP 에이전트에 생성하면 OpenClaw는 기본적으로 대상 에이전트의 작업 공간을 상속합니다. 상속된 경로가 없으면(ENOENT/ENOTDIR) 백엔드 기본값으로 폴백합니다. 그 외의 접근 오류(예: EACCES)는 생성 오류로 표시됩니다.
• 바인딩된 대화에서도 Gateway 관리 명령은 로컬에 유지됩니다. 일반 후속 텍스트가 바인딩된 ACP 세션으로 라우팅되더라도 /acp ... 명령은 OpenClaw가 처리합니다. 해당 화면에서 명령 처리가 활성화되어 있으면 /status와 /unfocus도 항상 로컬에 유지됩니다.

채널 어댑터에서 스레드 바인딩이 활성화된 경우:

• OpenClaw는 스레드를 대상 ACP 세션에 바인딩합니다.
• 해당 스레드의 후속 메시지는 바인딩된 ACP 세션으로 라우팅됩니다.
• ACP 출력은 같은 스레드로 다시 전달됩니다.
• 포커스 해제/닫기/보관/유휴 시간 초과 또는 최대 수명 만료 시 바인딩이 제거됩니다.
• /acp close, /acp cancel, /acp status, /status, /unfocus는 ACP 하네스에 보내는 프롬프트가 아니라 Gateway 명령입니다.

스레드 바인딩 ACP에 필요한 기능 플래그:

• acp.enabled=true
• acp.dispatch.enabled는 기본적으로 켜져 있습니다(자동 ACP 스레드 디스패치를 일시 중지하려면 false로 설정하세요. 명시적 sessions_spawn({ runtime: "acp" }) 호출은 계속 작동합니다).
• 채널 어댑터의 스레드 세션 생성 활성화(기본값: true):
  • Discord: channels.discord.threadBindings.spawnSessions=true
  • Telegram: channels.telegram.threadBindings.spawnSessions=true

스레드 바인딩 지원은 어댑터마다 다릅니다. 활성 채널 어댑터가 스레드 바인딩을 지원하지 않으면 OpenClaw는 명확한 미지원/사용 불가 메시지를 반환합니다.

• 세션/스레드 바인딩 기능을 노출하는 모든 채널 어댑터.
• 현재 기본 제공 지원: Discord 스레드/채널, Telegram 토픽(그룹/슈퍼그룹의 포럼 토픽 및 DM 토픽).
• Plugin 채널은 같은 바인딩 인터페이스를 통해 지원을 추가할 수 있습니다.

대화형 세션은 표시되는 채팅 표면에서 대화를 계속하기 위한 것입니다.

• /acp spawn ... --bind here는 현재 대화를 ACP 세션에 바인딩합니다.
• /acp spawn ... --thread ...는 채널 스레드/주제를 ACP 세션에 바인딩합니다.
• 지속형으로 구성된 bindings[].type="acp"는 일치하는 대화를 동일한 ACP 세션으로 라우팅합니다.

바인딩된 대화의 후속 메시지는 ACP 세션으로 직접 라우팅되고, ACP 출력은 동일한 채널/스레드/주제로 다시 전달됩니다.

OpenClaw가 하네스로 전송하는 내용:

• 일반적인 바인딩 후속 메시지는 프롬프트 텍스트로 전송되며, 하네스/백엔드가 지원하는 경우에만 첨부 파일도 함께 전송됩니다.
• /acp 관리 명령과 로컬 Gateway 명령은 ACP 디스패치 전에 가로챕니다.
• 런타임에서 생성된 완료 이벤트는 대상별로 구체화됩니다. OpenClaw 에이전트는 OpenClaw의 내부 런타임 컨텍스트 봉투를 받고, 외부 ACP 하네스는 하위 결과와 지침이 포함된 일반 프롬프트를 받습니다. 원시 <<&lt;BEGIN_OPENCLAW_INTERNAL_CONTEXT&gt;>> 봉투는 외부 하네스로 전송되거나 ACP 사용자 대화 기록 텍스트로 저장되어서는 안 됩니다.
• ACP 대화 기록 항목은 사용자에게 표시되는 트리거 텍스트 또는 일반 완료 프롬프트를 사용합니다. 내부 이벤트 메타데이터는 가능한 경우 OpenClaw에서 구조화된 상태로 유지되며 사용자가 작성한 채팅 콘텐츠로 취급되지 않습니다.

다른 에이전트 실행에서 생성한 일회성 ACP 세션은 하위 에이전트와 유사한 백그라운드 하위 작업입니다.

• 상위 작업은 sessions_spawn({ runtime: "acp", mode: "run" })으로 작업을 요청합니다.
• 하위 작업은 자체 ACP 하네스 세션에서 실행됩니다.
• 하위 턴은 네이티브 하위 에이전트 생성에 사용되는 것과 동일한 백그라운드 레인에서 실행되므로, 느린 ACP 하네스가 관련 없는 기본 세션 작업을 차단하지 않습니다.
• 완료는 작업 완료 알림 경로를 통해 상위 작업에 보고됩니다. OpenClaw는 내부 완료 메타데이터를 외부 하네스로 보내기 전에 일반 ACP 프롬프트로 변환하므로 하네스에는 OpenClaw 전용 런타임 컨텍스트 마커가 표시되지 않습니다.
• 사용자에게 표시되는 응답이 유용한 경우 상위 작업은 하위 결과를 일반적인 어시스턴트 어조로 다시 작성합니다.

이 경로를 상위 작업과 하위 작업 간의 P2P 채팅으로 취급하지 마세요. 하위 작업에는 이미 상위 작업으로 돌아가는 완료 채널이 있습니다.

sessions_send는 생성 후 다른 세션을 대상으로 지정할 수 있습니다. 일반 피어 세션의 경우 OpenClaw는 메시지를 주입한 후 에이전트 간(A2A) 후속 경로를 사용합니다.

• 대상 세션의 응답을 기다립니다.
• 선택적으로 요청자와 대상이 제한된 횟수의 후속 턴을 교환하도록 합니다.
• 대상에 알림 메시지를 생성하도록 요청합니다.
• 해당 알림을 표시되는 채널 또는 스레드로 전달합니다.

해당 A2A 경로는 송신자에게 표시되는 후속 응답이 필요한 피어 전송을 위한 폴백입니다. 예를 들어 광범위한 tools.sessions.visibility 설정에서 관련 없는 세션이 ACP 대상을 보고 메시지를 보낼 수 있는 경우에도 활성화된 상태로 유지됩니다.

OpenClaw는 요청자가 자체 부모 소유의 일회성 ACP 자식 세션의 부모인 경우에만 A2A 후속 응답을 건너뜁니다. 이 경우 작업 완료 처리에 더해 A2A를 실행하면 자식 세션의 결과로 부모를 깨우고, 부모의 응답을 다시 자식 세션으로 전달하여 부모/자식 에코 루프가 생성될 수 있습니다. 해당 소유 자식 세션의 경우에는 완료 경로가 이미 결과를 전달할 책임이 있으므로 sessions_send 결과가 delivery.status="skipped"를 보고합니다.

새로 시작하는 대신 resumeSessionId를 사용하여 이전 ACP 세션을 계속 진행합니다. 에이전트는 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"일 때만 적용됩니다. 기본 하위 에이전트 런타임은 이 ACP 전용 필드를 무시합니다.
• streamTo는 runtime: "acp"일 때만 적용됩니다. 기본 하위 에이전트 런타임은 이 ACP 전용 필드를 무시합니다.
• resumeSessionId는 호스트 로컬 ACP/하네스 재개 ID이며 OpenClaw 채널 세션 키가 아닙니다. OpenClaw는 디스패치 전에 ACP 생성 정책과 대상 에이전트 정책을 계속 확인하며, 해당 업스트림 ID를 로드할 권한 부여는 ACP 백엔드 또는 하네스가 담당합니다.
• resumeSessionId는 업스트림 ACP 대화 기록을 복원합니다. thread와 mode는 새로 생성하는 OpenClaw 세션에 여전히 정상적으로 적용되므로 mode: "session"에는 계속 thread: true가 필요합니다.
• 대상 에이전트는 session/load를 지원해야 합니다(Codex와 Claude Code는 지원함).
• 세션 ID를 찾을 수 없으면 명확한 오류와 함께 생성에 실패하며, 새 세션으로 자동 폴백하지 않습니다.

Gateway를 배포한 후에는 단위 테스트만 신뢰하지 말고 실제 엔드투엔드 검사를 실행합니다.

1. 대상 호스트에 배포된 Gateway 버전과 커밋을 확인합니다.
2. 실제 에이전트에 임시 ACPX 브리지 세션을 엽니다.
3. 해당 에이전트에게 runtime: "acp", agentId: "codex", mode: "run" 및 작업 Reply with exactly LIVE-ACP-SPAWN-OK를 사용하여 sessions_spawn을 호출하도록 요청합니다.
4. accepted=yes, 실제 childSessionKey, 검증기 오류 없음이 확인되는지 검증합니다.
5. 임시 브리지 세션을 정리합니다.

게이트는 mode: "run"으로 유지하고 streamTo: "parent"는 건너뜁니다. 스레드에 바인딩된 mode: "session"과 스트림 릴레이 경로는 별도의 더 포괄적인 통합 검사입니다.