메인 Agent에서 sessions_spawn으로 서브 작업을 띄웠는데 ACP_TURN_FAILED, invalid handshake 1008 또는 queue owner unavailable이 나고, 같은 Gateway 직접 채팅은 정상일 때——본문은 ① runtime=acp vs runtime=subagent 선택 시점；② streamTo/resumeSessionId가 acp 전용인 이유와 subagent 오설정 트리아지；③ ACP 핸드셰이크 실패 시 subagent 폴백·Windows OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE；④ Completions vs Responses streamTo 자동 채움 차이를 답합니다. 업그레이드 호위 ACP 트리아지, Docker 서브에이전트 1008 페어링과 보완——본문은 멀티 Agent runtime 선택만 다룹니다.
runtime=acp인데 ACP bridge 미구비: 메인 채널은 대화되나 spawn 즉시 ACP_TURN_FAILED——원인은 acpx 미등록·queue owner 오프라인이며 모델 쿼터가 아닙니다.runtime=subagent에 streamTo/resumeSessionId 입력: ACP 세션 연속 전용 필드입니다. subagent는 Gateway 내장 RPC 경로로, 오설정 시 파라미터 무효 또는 필드 조용히 폐기——「서브 Agent가 컨텍스트를 못 받음」처럼 보입니다.OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE로 연장·재시도하십시오.streamTo 추론, Completions는 안 함——spawn 고장으로 오인하기 쉬우며 API 형태·runtime 불일치입니다.2026 upstream은 sessions_spawn을 두 상호 배타 runtime으로 분리합니다: runtime=acp는 ACP bridge로 외부 acpx와 통신·streamTo로 서브 출력을 메인 UI에 환류；runtime=subagent는 Gateway 프로세스 내 경량 서브에이전트——지연 낮고 acpx 비의존, ACP 연속 필드는 미지원. runtime 오선택+잘못된 필드는 on-call 최악의 「가짜 복잡성」——경로 정렬 후 모델·allowlist(tools.profile 트리아지)를 논의하십시오.
실무에서는 매 spawn 호출을 스케줄링 계약으로 기록하십시오: runtime, UI 환류 의존, 메인 세션 Completions/Responses, 실패 시 폴백(subagent/롤백). 계약 없이는 「어제 spawn 됐는데 오늘 안 됨」 설명이 어렵습니다——변경은 Gateway 프로세스보다 템플릿 필드·API 형태에 있습니다.
| 사이트 기존 장문 | 본문 범위 | 본문에서 반복 안 함 |
|---|---|---|
| 업그레이드 호위 ACP 트리아지 | spawn 시 acp vs subagent 선택·폴백 | backup create, gateway probe 전 사다리 |
| Docker 서브에이전트 1008 | subagent 경로와 pairing 1008 경계 | Compose trustedProxies 단계 명령 |
| tools.profile 트리아지 | spawn 성공 후 「서브 Agent 도구 없음」 2차 조사 | allowlist 3층 전문 |
| SSH 상시 Gateway | 원격 Mac acpx·subagent 공존 토폴로지 | 포트 포워딩·launchd 세부 |
runtime=acp vs runtime=subagent: 언제 어느 스택선택 구호: UI 환류·기존 ACP 세션 연속·Cursor/IDE acpx 정렬 → acp；Gateway 내 폐루프·저의존·acp 불가 → subagent. 아래는 프로덕션 네 가지 작업 형태(80% 티켓 커버):
| 작업 형태 | 권장 runtime | 핵심 파라미터 | 피할 것 |
|---|---|---|---|
| 서브 Agent 출력을 메인 채팅에 스트리밍 환류 | acp |
streamTo→메인 session；선택 resumeSessionId |
subagent+streamTo(무효 조합) |
| 백그라운드 배치, UI 환류 불필요 | subagent |
task+타임아웃；streamTo 없음 |
억지 acp로 bridge 장애면 확대 |
| ACP bridge queue owner unavailable | 임시 subagent |
티켓에 폴백 기록；병행 acpx 등록 수리 | acp 반복 재시도로 MTTR 상승 |
| 멀티 컨테이너 Docker, RPC healthy·spawn 1008 | 페어링/네트워크 수리 후 subagent |
trustedProxies 대조；Docker 전문 | bind 미수리 상태 runtime 전환 |
streamTo / resumeSessionId: acp 전용 오설정 트리아지「spawn 파라미터는 맞는데 서브 Agent 빈 응답」 다수는 필드·runtime 교차 오염입니다. Gateway는 subagent 경로에서 ACP 전용 필드를 제거·거부합니다. Completions 예시에서 streamTo:"main"을 복사했는데 실제가 runtime=subagent면 로그는 일반 RPC error만——호출 JSON 대조가 필요합니다.
runtime=acp에서 resumeSessionId는 기존 acpx 세션 연속(동일 스레드 다중 spawn), streamTo는 서브 토큰 스트림을 Control UI·지정 channel로 보냅니다. 2026 Responses 라우팅은 일부 설정에서 streamTo 자동 추론(메인이 Responses·미명시 시)；Completions는 자동 채움 없음——Responses→Completions 이전 후 spawn 템플릿 미수정 시 「예전엔 환류, 지금은 백그라운드 완료」 회귀. upgrade 무관, API+runtime 조합 문제입니다.
필드 박리 실험: 실패 JSON 복제→streamTo·resumeSessionId 제거→runtime=subagent 재시도. 즉시 성공이면 ACP 경로·오설정 거의 확정；실패 시 pairing·Token·도구면. Runbook 4단계에 기록해 acp 로그 공회전을 막으십시오.
// ✅ acp: UI 환류 + 선택적 연속
{
"tool": "sessions_spawn",
"runtime": "acp",
"task": "경쟁사 가격 조사 후 표 출력",
"streamTo": "main",
"resumeSessionId": "acp-sess-abc123"
}
// ✅ subagent: Gateway 내 폐루프, streamTo 금지
{
"tool": "sessions_spawn",
"runtime": "subagent",
"task": "logs 디렉터리 파일 일괄 이름 변경"
}
// ❌ 흔한 오설정: subagent에 ACP 필드
{
"runtime": "subagent",
"streamTo": "main"
}
ACP_TURN_FAILED, 1008, queue ownerruntime=acp 실패·메인 채팅 정상 시 로그 지문으로 분류——「Gateway 완전 무응답」과 혼조사 금지(후자는 채널/모델 전문).
| 로그/증상 | 우선 의심 | 1차 조치 |
|---|---|---|
ACP_TURN_FAILED |
acpx 미준비；turn 타임아웃 | Windows OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1；bridge 등록 확인 |
| invalid handshake / WebSocket 1008 | CLI/Gateway/acpx 버전 분열；헤더 불일치 | 동일 버전 정렬；단일 reload；핀 매트릭스 |
| queue owner unavailable | ACP bridge 등록 소실(2026.3.x 회귀 구간) | host acpx 확인；임시 runtime=subagent SLA |
| subagent도 1008 | 페어링/Token/네트워크(ACP 비전용) | Docker 1008 Runbook |
| spawn 성공·서브 Agent 도구 없음 | tools.profile / agent 오버라이드 | tools.profile 트리아지 |
폴백 전략: acp가 변경 창에서 연속 2회 실패(reload 후 재검 포함)하고 subagent 단독 최소 작업 프로브 통과 시, 티켓에 「임시 runtime=subagent」 명시·UI 환류 작업 제한——acpx 수리 후 acp 복귀. 불량 digest 롤백과 직교: 폴백=SLA, 롤백=알려진 regression 수리.
OPENCLAW_ACPX_RUNTIME_STARTUP_PROBEWindows에서 provider 확장·Defender가 acpx 콜드스타트를 수 초 지연——bridge 준비 전 spawn은 ACP_TURN_FAILED 또는 invalid handshake로 보입니다. OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1(의미는 설치 버전 문서 기준)로 첫 spawn 전 acpx 헬스 프로브 추가 대기. 계속 실패 시 동일 머신 subagent 최소 작업으로 Gateway 스케줄링 스택 자체 검증 후 acpx 설치/권한 격리——Windows 기동 지연을 「OpenClaw 버전 롤백 필수」로 오판하지 마십시오.
업그레이드 호위와 분업: 호위=버전 이전 후 probe/ACP 전역 회귀；본문=버전 안정 후 spawn 스케줄링 오선택·핸드셰이크 간헐 실패. 연계 시 upgrade 사다리 통과 먼저——아니면 split-brain을 streamTo 오설정으로 오판합니다.
# Windows: acpx 기동 프로브 연장(예) $env:OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE = "1" openclaw gateway status openclaw gateway probe # 최소 subagent 프로브(streamTo 없음) # Control UI 또는 CLI에서 동등 sessions_spawn, runtime=subagent
| 영향면 | acp 수리 지속(설정/bridge) | 임시 runtime=subagent | 핀/롤백 |
|---|---|---|---|
| spawn/acp만 적색, 메인·subagent 프로브 정상 | acpx 등록·startup probe | 권장: UI 환류 불필요 작업 subagent | 알려진 regression 구간에서만 |
| acp+subagent 동시 실패, probe도 적색 | backup 복원 후 단계 시도만 | 1순위 아님 | 우선 backup 또는 digest 롤백 |
| UI 환류 필수, acp 불가 | bridge 수리 전 업무 피해 | streamTo 대체 불가 | 롤백 평가 또는 원격 Mac 상시 Gateway |
runtime, streamTo/resumeSessionId 유무, 메인 API(Completions/Responses).openclaw gateway status+gateway probe；업그레이드 후 단일 reload(업그레이드 호위).OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE；1008/queue owner 로그.sessions_spawn 성공/총 호출；acp <95%·subagent 정상→모델 교체보다 bridge 수리.runtime=subagent 호출에 streamTo/resumeSessionId 잔존 감사；목표 0(lint·템플릿 검토).노트북 Gateway에 acpx·절전·다중 provider 플러그인 혼재 시 spawn 실패가 「OpenClaw 불안정」으로 오기록됩니다. 권위 Gateway·acpx를 상시 전원 원격 Mac에 공존, 로컬은 SSH Control UI 포워딩만——spawn·probe 동일 노드 수락·로그 타임라인 정렬.
prompt만 반복하고 runtime·streamTo 정합 미확인 시 ACP 핸드셰이크가 「멀티 Agent 불가」 착시로 확대됩니다. acp/subagent 매트릭스·오설정 트리아지·subagent 폴백을 runbook에 쓰면 on-call을 밤샘 맹시도에서 프로브·폴백·지표 있는 분 단위 사건으로 압축합니다.
Windows 노트북·Docker 분리 컨테이너에서 acp bridge를 억지로 유지하면 세 가지 숨은 비용(기동 경합 가짜 1008, Completions/Responses streamTo 불일치, 장애면 중첩)을 감수해야 합니다. 7×24·spawn 티켓화·acp/subagent 전환 프로덕션 Gateway는 MACCOME Mac mini(M4/M4 Pro)·6개 지역 유연 리스가 덮개 닫힌 노트북 queue owner 싸움보다 총비용 유리한 경우가 많습니다. 다중 지역 노드·리스 가이드와 SSH 상시 Runbook으로 토폴로지 연결하십시오.
자주 묻는 질문
streamTo와 resumeSessionId를 runtime=subagent에서 쓸 수 있습니까?
없습니다. runtime=acp ACP 연속·UI 환류 전용입니다. subagent는 task 등 Gateway 내장 필드만. 템플릿 검토는 임대 요금 프로덕션 노드 티켓화를 참고하십시오.