ACP 에이전트

• plugins.allow가 설정되어 있으면 이는 제한적인 Plugin 인벤터리이므로 반드시 acpx를 포함해야 합니다. 그렇지 않으면 설치된 ACP 백엔드가 의도적으로 차단되고 /acp doctor가 누락된 허용 목록 항목을 보고합니다.
• Codex ACP 어댑터는 acpx Plugin과 함께 준비되며, 가능하면 로컬에서 실행됩니다.
• 다른 대상 하네스 어댑터는 처음 사용할 때 여전히 필요에 따라 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 세션을 종료하고 바인딩을 제거합니다. 하네스가 재개를 지원하는 경우 자체 업스트림 기록은 계속 유지할 수 있습니다.
• 유휴 런타임 워커는 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 지원 계약에 문서화되어 있습니다.

• openai-codex/* - PI Codex OAuth/구독 경로.
• openai/* 및 agentRuntime.id: "codex" - 네이티브 Codex 앱 서버 내장 런타임.
• /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는 Gateway 명령이며, ACP 하니스에 대한 프롬프트가 아닙니다.

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

• acp.enabled=true
• acp.dispatch.enabled는 기본적으로 켜져 있습니다(false로 설정하면 자동 ACP 스레드 디스패치를 일시 중지합니다. 명시적 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 사용자 transcript 텍스트로 유지되어서는 안 됩니다.
• ACP transcript 항목은 사용자에게 보이는 트리거 텍스트 또는 일반 완료 프롬프트를 사용합니다. 내부 이벤트 메타데이터는 가능한 경우 OpenClaw에서 구조화된 상태로 유지되며 사용자가 작성한 채팅 콘텐츠로 취급되지 않습니다.

다른 에이전트 실행에서 스폰된 일회성 ACP 세션은 하위 에이전트와 비슷한 백그라운드 자식입니다.

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

이 경로를 부모와 자식 간의 피어 투 피어 채팅으로 취급하지 마세요. 자식에는 이미 부모로 돌아가는 완료 채널이 있습니다.

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

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

이 A2A 경로는 발신자에게 보이는 후속 응답이 필요한 피어 전송을 위한 폴백입니다. 예를 들어 넓은 tools.sessions.visibility 설정 아래에서 관련 없는 세션이 ACP 대상을 보고 메시지를 보낼 수 있을 때 계속 활성화됩니다.

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

새로 시작하는 대신 이전 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"일 때만 적용됩니다. 기본 하위 에이전트 런타임은 이 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 배포 후에는 단위 테스트를 신뢰하는 대신 라이브 end-to-end 검사를 실행하세요.

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"과 스트림 릴레이 경로는 별도의 더 풍부한 통합 패스입니다.