ACP 하네스 라우터

ACP 하네스 라우터은(는) 무엇을 하나요?

사용자 의도가 "이것을 Claude Code/Cursor/Copilot/OpenClaw/OpenCode/Gemini/Grok Build/Qwen/Kiro/Kimi/iFlow/Droid/Kilocode(ACP 하네스)에서 실행하라"일 때, 하위 에이전트 런타임이나 PTY 스크래핑을 사용하지 마세요. ACP를 인식하는 흐름을 통해 라우팅하세요.

Codex는 특별합니다: 일반 채팅/대화 바인딩 및 제어는 기본 ACP 경로 대신 네이티브 Codex 앱-서버 플러그인(/codex bind, /codex threads, /codex resume)을 사용해야 합니다. 사용자가 명시적으로 ACP//acp/acpx를 언급하거나, 네이티브 Codex 런타임 스폰을 아직 사용할 수 없는 sessions_spawn을 통해 백그라운드 자식 세션을 생성할 때만 Codex에 ACP를 사용하세요.

의도 감지

사용자가 OpenClaw에게 다음을 요청할 때 이 스킬을 트리거하세요:

• Claude Code / Cursor / Copilot / OpenClaw / OpenCode / Gemini / Grok Build / Qwen / Kiro / Kimi / iFlow / Droid / Kilocode에서 무언가를 실행
• ACP, /acp 또는 acpx를 통해 명시적으로 Codex 실행
• 기존 하네스 작업 계속
• 외부 코딩 하네스에 지침 전달
• 외부 하네스 대화를 스레드 같은 대화로 유지

코딩 에이전트 스레드 요청에 대한 필수 사전 확인:

• ACP 하네스 작업을 위한 스레드를 생성하기 전에, 동일한 턴에서 이 스킬을 먼저 읽으세요.
• 읽은 후 아래 'OpenClaw ACP 런타임 경로'를 따르세요. ACP 하네스 스레드 생성을 위해 message(action="thread-create")를 사용하지 마세요.

모드 선택

다음 경로 중 하나를 선택하세요:

1. OpenClaw ACP 런타임 경로(기본값): sessions_spawn / ACP 런타임 도구를 사용하세요.
2. 직접 acpx 경로(전화 게임): exec를 통해 acpx CLI를 사용하여 하네스 세션을 직접 구동하세요.

다음 중 하나가 참일 때 직접 acpx를 사용하세요:

• 사용자가 직접 acpx 구동을 명시적으로 요청
• ACP 런타임/플러그인 경로를 사용할 수 없거나 비정상
• 작업이 "하네스에 프롬프트만 전달"이고 OpenClaw ACP 수명 주기 기능이 필요하지 않음

다음을 사용하지 마세요:

• 하네스 제어를 위한 subagents 런타임
• 사용자 요구 사항으로서의 /acp 명령 위임
• acpx를 사용할 수 있을 때 지원되는 ACP 하네스 CLI의 PTY 스크래핑

AgentId 매핑

사용자가 하네스를 직접 지정할 때 다음 기본값을 사용하세요:

• "openclaw" -> agentId: "openclaw"
• "claude" 또는 "claude code" -> agentId: "claude"
• "codex" -> agentId: "codex" (명시적 ACP/acpx 요청 또는 백그라운드 ACP 런타임 스폰에만 해당)
• "copilot" 또는 "github copilot" -> agentId: "copilot"
• "cursor" 또는 "cursor cli" -> agentId: "cursor"
• "droid" 또는 "factory droid" -> agentId: "droid"
• "opencode" -> agentId: "opencode"
• "gemini" 또는 "gemini cli" -> agentId: "gemini"
• "grok build" 또는 "grok-build" -> agentId: "grok-build"
• "iflow" -> agentId: "iflow"
• "kilocode" -> agentId: "kilocode"
• "kimi" 또는 "kimi cli" -> agentId: "kimi"
• "kiro" 또는 "kiro cli" -> agentId: "kiro"
• "qwen" 또는 "qwen code" -> agentId: "qwen"

이 기본값은 현재 acpx 내장 별칭과 일치합니다.

grok-build는 ACPX 에이전트 대상이며, xAI 모델 ID xai/grok-build-0.1이 아닙니다. grok-build를 agentId를 통해 라우팅하세요. 정규화된 xAI 참조는 OpenClaw model 필드에서만 사용하세요.

정책이 선택된 ID를 거부하면 정책 오류를 명확히 보고하고 허용된 ACP 에이전트 ID를 요청하세요.

OpenClaw ACP 런타임 경로

필수 동작:

1. ACP 하네스 스레드 스폰 요청의 경우, 도구를 호출하기 전에 동일한 턴에서 이 스킬을 먼저 읽으세요.
2. sessions_spawn을 다음과 함께 사용하세요:
   • runtime: "acp"
   • thread: true
   • mode: "session" (사용자가 명시적으로 원샷을 원하지 않는 한)
3. ACP 하네스 스레드 생성의 경우, action=thread-create와 함께 message를 사용하지 마세요. sessions_spawn이 유일한 스레드 생성 경로입니다.
4. 요청된 작업을 task에 넣어 ACP 세션이 즉시 가져가도록 하세요.
5. ACP 기본 에이전트가 알려지지 않은 경우 명시적으로 agentId를 설정하세요.
6. 이 경로가 직접 작동할 때 사용자에게 슬래시 명령이나 CLI를 실행하도록 요청하지 마세요.

예시:

사용자: "스레드에서 테스트 codex ACP 세션을 생성하고 안녕이라고 말하라고 해"

호출:

{
  "task": "안녕이라고 말해.",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

스레드 스폰 복구 정책

사용자가 스레드에서 코딩 하네스를 시작하도록 요청하면 이를 ACP 런타임 요청으로 처리하고 종단 간 만족시키려고 시도하세요.

ACP 백엔드를 사용할 수 없을 때 필요한 동작:

1. 즉시 사용자에게 대체 경로를 선택하도록 요청하지 마세요.
2. 먼저 자동 로컬 복구를 시도하세요:
   • 플러그인-로컬 고정 acpx가 ACPX 플러그인 패키지에 설치되어 있는지 확인
   • ${ACPX_CMD} --version 확인
3. 재설치/복구 후 게이트웨이를 다시 시작하고 사용자 대신 해당 재시작을 실행하겠다고 명시적으로 제안하세요.
4. 복구 후 ACP 스레드 스폰을 한 번 재시도하세요.
5. 복구+재시도가 실패한 경우에만 구체적인 오류를 보고하고 대체 옵션을 제공하세요.

대체 옵션을 제공할 때 ACP를 먼저 유지하세요:

• 옵션 1: 정확히 실패한 단계를 보여준 후 ACP 스폰 재시도
• 옵션 2: 직접 acpx 전화-게임 방식

이러한 요청에 대해 기본적으로 하위 에이전트 런타임을 사용하지 마세요.

ACPX 설치 및 버전 정책 (직접 acpx 경로)

이 저장소의 경우, 직접 acpx 호출은 @openclaw/acpx 확장 패키지와 동일한 고정 정책을 따라야 합니다.

1. 전역 PATH보다 플러그인-로컬 바이너리를 선호하세요:
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx
2. 확장 종속성에서 고정 버전을 확인하세요:
   • node -e "console.log(require(process.env.ACPX_PLUGIN_ROOT + '/package.json').dependencies.acpx)"
3. 바이너리가 없거나 버전이 일치하지 않으면 플러그인-로컬 고정 버전을 설치하세요:
   • cd "$ACPX_PLUGIN_ROOT" && npm install --omit=dev --no-save acpx@<pinnedVersion>
4. 사용 전에 확인:
   • ${ACPX_PLUGIN_ROOT}/node_modules/.bin/acpx --version
5. 설치/복구로 ACPX 아티팩트가 변경된 경우 게이트웨이를 다시 시작하고 재시작 실행을 제안하세요.
6. 사용자가 명시적으로 전역 설치를 요청하지 않는 한 npm install -g acpx를 실행하지 마세요.

설정 및 재사용:

ACPX_PLUGIN_ROOT="<bundled-acpx-plugin-root>"
ACPX_CMD="$ACPX_PLUGIN_ROOT/node_modules/.bin/acpx"

직접 acpx 경로 ("전화 게임")

이 경로를 사용하여 /acp 또는 하위 에이전트 런타임 없이 하네스 세션을 구동하세요.

규칙

1. ${ACPX_CMD}를 호출하는 exec 명령을 사용하세요.
2. 대화당 안정적인 세션 이름을 재사용하여 후속 프롬프트가 동일한 하네스 컨텍스트에 유지되도록 하세요.
3. 사용자에게 다시 전달할 깨끗한 어시스턴트 텍스트를 위해 --format quiet를 선호하세요.
4. 사용자가 원샷 동작을 원할 때만 exec(원샷)을 사용하세요.
5. 작업 범위가 저장소 컨텍스트에 의존할 때 작업 디렉토리를 명시적으로(--cwd) 유지하세요.

세션 이름 지정

예를 들어 안정적인 이름을 사용하세요:

• oc-<harness>-<conversationId>

여기서 conversationId는 가능한 경우 스레드 ID이고, 그렇지 않으면 채널/대화 ID입니다.

명령 템플릿

지속적 세션 (없으면 생성 후 프롬프트):

${ACPX_CMD} codex sessions show oc-codex-<conversationId> \
  || ${ACPX_CMD} codex sessions new --name oc-codex-<conversationId>

${ACPX_CMD} codex -s oc-codex-<conversationId> --cwd <workspacePath> --format quiet "<prompt>"

원샷:

${ACPX_CMD} codex exec --cwd <workspacePath> --format quiet "<prompt>"

진행 중인 턴 취소:

${ACPX_CMD} codex cancel -s oc-codex-<conversationId>

세션 종료:

${ACPX_CMD} codex sessions close oc-codex-<conversationId>

acpx의 하네스 별칭

• claude
• codex
• copilot
• cursor
• droid
• gemini
• grok-build
• iflow
• kilocode
• kimi
• kiro
• openclaw
• opencode
• qwen

acpx의 내장 어댑터 명령

기본값은 다음과 같습니다:

• openclaw -> openclaw acp
• claude -> bundled @agentclientprotocol/[email protected]
• codex -> bundled @agentclientprotocol/[email protected] through OpenClaw's isolated CODEX_HOME wrapper
• copilot -> copilot --acp --stdio
• cursor -> cursor-agent acp
• droid -> droid exec --output-format acp
• gemini -> gemini --acp
• grok-build -> grok agent stdio
• iflow -> iflow --experimental-acp
• kilocode -> npx -y @kilocode/cli acp
• kimi -> kimi acp
• kiro -> kiro-cli acp
• opencode -> npx -y opencode-ai acp
• qwen -> qwen --acp

~/.acpx/config.json이 agents를 재정의하면 해당 재정의가 기본값을 대체합니다. 로컬 Cursor 설치가 여전히 ACP를 agent acp로 노출하는 경우, cursor 에이전트 재정의를 명시적으로 설정하세요.

실패 처리

• acpx: command not found:
  • 스레드-스폰 ACP 요청의 경우, ACPX 플러그인 패키지에 플러그인-로컬 고정 acpx를 즉시 설치
  • 설치 후 게이트웨이를 다시 시작하고 재시작을 자동으로 실행하겠다고 제안
  • 그런 다음 한 번 재시도
  • 정책이 명시적으로 요구하지 않는 한 설치 권한을 먼저 묻지 마세요.
  • 명시적으로 요청되지 않는 한 전역 acpx를 설치하지 마세요.
• 어댑터 명령 누락 (예: claude-agent-acp를 찾을 수 없음):
  • 스레드-스폰 ACP 요청의 경우, 먼저 손상된 ~/.acpx/config.json 에이전트 재정의를 제거하여 내장 기본값을 복원
  • 그런 다음 대체 옵션을 제공하기 전에 한 번 재시도
  • 사용자가 바이너리 기반 재정의를 원하는 경우, 정확히 구성된 어댑터 바이너리 설치
• NO_SESSION: ${ACPX_CMD} <agent> sessions new --name <sessionName>을 실행한 후 프롬프트를 재시도하세요.
• 큐 사용 중: 완료를 기다리거나(기본값), 비동기 동작이 명시적으로 필요한 경우 --no-wait를 사용하세요.

출력 전달

사용자에게 전달할 때 acpx 명령 결과의 최종 어시스턴트 텍스트 출력을 반환하세요. 사용자가 자세한 로그를 요청하지 않는 한 원시 로컬 도구 노이즈를 전달하지 마세요.