acpx FAQ
acpx (>= 0.19.3)를 통해 코딩 에이전트를 헤드리스로 구동합니다.
구문 권위
구문은 이 파일이 아닌 바이너리에서 비롯됩니다. acpx --skill show acpx가 공급업체 참조(~43k 문자)이며 명령 형태의 결정적 기준입니다. 이를 대화록에 덤프하지 마십시오. 다음 순서로 검색하십시오.
acpx --help/acpx <cmd> --help- 구성하려는 플래그들.- 주제 하나:
acpx --skill show acpx | rg -B2 -A12 '<term>', 또는 섹션:acpx --skill show acpx | sed -n '/^## Sessions/,/^## /p'. - 새로운 것(흐름, 임베디드 런타임)을 작성하는 경우: 스크래치 파일에 한 번 덤프하고 해당 파일을 grep하십시오.
이 파일은 참조 문서가 다루는 내용을 반복하지 않습니다. 참조 문서에 없는 내용만 포함합니다: 종료 코드, 실패 의미론, 함정, 에이전트별 레시피. 구문 질문에 대한 답이 여기에 없으면 거기에 있습니다 - 가서 가져오고, 플래그를 추측하지 마십시오. 저장소의 docs/ (exit-codes, session-control, session-watch, permissions, config)는 제공된 참조 문서가 생략한 일부를 다룹니다.
이 차선을 사용하는 경우
acpx는 헤드리스 아웃오브프로세스 실행자 차선입니다: 일반 터미널, ssh 또는 cron에서 스크립트나 다른 에이전트에 의해 구동되는, 벤더나 계정이 다른 또 다른 에이전트입니다. 세션 내 팬아웃은 하네스 자체의 서브에이전트 도구에 남아 있습니다.
불변 규칙
-
전역 플래그는 에이전트 하위 명령 앞에 옵니다 (
--cwd,--model,--approve-all,--agent,--format,--timeout,--ttl,--mcp-config). 프롬프트 형식은 오직-s,--no-wait,-f(그리고exec는 또한--config-option)만 허용합니다; 다른 하위 명령은 각자의 플래그를 가집니다 (sessions watch --cursor,sessions export|import --cwd). 에이전트 뒤에 오는 전역 플래그는error: unknown option과 함께 1로 종료됩니다; 에이전트 앞의 잘못된 플래그는 2로 종료됩니다. -
-s <name>은 절대 세션을 생성하지 않습니다.--cwd에서 시작하여 가장 가까운.git까지 올라가며 해석합니다 - 디렉토리 또는 파일이므로 각 작업 트리와 서브모듈은 자체 경계입니다; git 외부에서는 정확한--cwd만 확인됩니다. 일치하는 항목이 없으면 4로 종료됩니다. 같은 디렉토리에서 먼저sessions ensure --name <n>으로 생성하십시오. -
status는 턴 신호가 아닙니다. 큐 소유자 프로세스를 조사하며, 에이전트는 절대 조사하지 않고, 턴이 끝난 후에도 계속running이라고 말합니다. 자동화를 이에 게이트하지 마십시오. -
권한 플래그는 샌드박스가 아닙니다.
- claude: 어댑터는 Claude 설정의
permissions.defaultMode에서 시작합니다 (acceptEdits/auto는 묻지 않고 편집 승인). 해당 모드가 에스컬레이션하는 것만 acpx에 권한 요청으로 도달합니다 ---deny-all은 이를 거부하지만(종료 5), 자동 승인된 편집은 절대 묻지 않습니다. - codex: (
--cwd와 임시 디렉토리에 루팅된) 자체 작업 공간 쓰기 샌드박스 내부의 쓰기는 요청을 발생시키지 않으므로,--deny-all도 여전히 쓰기를 수행합니다; 외부는Operation not permitted로 실패합니다 - 연결된 작업 트리의 gitdir을 포함하므로,git worktree의 샌드박스 차선은 커밋할 수 없습니다 (index.lock: Operation not permitted).config.toml이network_access를 활성화하지 않으면 네트워크는 꺼집니다.--approve-all은 어댑터의 모드를 변경하지 않습니다; 실행 시INITIAL_AGENT_MODE=read-only|agent|agent-full-access또는 라이브 세션에서codex set-mode agent-full-access -s <n>을 사용하면 변경됩니다. --allowed-tools/--max-turns는 오직 claude(그리고 qoder)에만 도달합니다; codex와 agy는 이를 무시합니다.--allowed-tools는 사전 승인할 뿐 제한하지 않습니다:--help의"" for no tools는 도구 없음이 아니라 승인 없음을 의미합니다.
실제 파일 시스템 제어는 어떤
--cwd를 건네느냐입니다. - claude: 어댑터는 Claude 설정의
-
[done] end_turn과 종료 0은 성공의 증거가 아닙니다. 콘텐츠 필터 종료, MCP 로드 실패, API 오류 (토큰 갱신 중 401, 모델 거부 400), 또는 잘린 턴은 모두 그렇게 끝납니다. 스트림을 읽거나, 에이전트가 확인 가능한 결과 파일을 쓰도록 요구하십시오. 팬아웃 전에 에이전트와 모델당 하나의 저렴한exec("OK 응답")은 인증 및 모델 오류를 잡아냅니다 - codex와 agy는 턴 전에 광고되지 않은--model을 거부하고, claude는 경고 후 전달합니다. -
영구 세션은 바쁘거나 웜 상태일 때만 상주 프로세스 스택을 유지합니다. 모든
-s프롬프트는npm exec -> node <adapter> -> <agent>(그리고 에이전트의 MCP 서버들)을 보유한 큐 소유자를 선출하며, MCP 전에 대략 550-650 MB입니다. 유휴 TTL(기본 300초) 후 소유자는 종료되고 세션은 계속 재개 가능합니다; 다음 프롬프트가 이를 다시 생성합니다.sessions close는 작업을 종료합니다 - 실행 라인에 체인으로 연결하십시오 (에이전트별 참조) 그래야 정리가 누군가의 기억에 의존하지 않습니다;--ttl 0은 자체 재수거를 제거합니다. 정리 참조.
에이전트별
일회성 디스패치: sessions ensure && prompt && sessions close, 하나의 체인 호출.
작업당 하나의 명명된 세션, 하나의 프롬프트, 결과 파일이 읽힐 때 종료됩니다.
&& 체인은 정리를 기계적으로 만듭니다 - 아무도 열린 레코드를 수거하지 않으며, 고아는 체인되지 않은 종료에서 발생합니다 - 반면 0이 아닌 실패(타임아웃 3, 권한 5)를 반환하는 턴은
자체적으로 종료를 건너뛰어 세션을 복구를 위해 열어 둡니다 (라이브 세션과 대화 참조). 외부에서 취소된 턴은 여전히 0으로 종료되므로, 종료 코드가 아닌 결과 파일이
성공 확인입니다 (불변 규칙 5). 예상된 후속 작업을 위해 세션을 유지하지 마십시오: 차단기의 상태는
대화 외부에 존재합니다(자격 증명은 시스템 수준이며, 부분 결과는 결과 파일에 속합니다) - 브리프와 해당 파일을 제공받은
새 세션으로 답하십시오. 재작업 - 세션 출력의 수정, 검토 또는 다듬기 - 도
새 세션을 얻습니다: 자신의 컨텍스트를 다시 읽는 에이전트는 새로운 시각이 잡는 것을 놓칩니다. 종료를 수행하는 실행 라인이 있는 세션에
절대 --no-wait을 사용하지 마십시오: 소유자 종료는 보류 중인 프롬프트를 조용히 드롭하고 활성 턴을 취소합니다(0.19.4에서 확인됨);
종료 전의 차단 프롬프트는 안전합니다. 기록할 가치가 없는 상태 없는 답변(사전 비행 "OK 응답")에는 exec를 사용하십시오.
세션은 에이전트 명령 + cwd + 이름을 키로 합니다; 각 병렬 실행자에게 고유한 이름과, 파일을 쓸 때 고유한
디렉토리(이상적으로는 하나의 작업 트리)를 제공하십시오.
어댑터는 어댑터 바이너리(claude-agent-acp,
codex-acp)가 PATH에 없으면 npm exec를 통해 실행됩니다 - 해당 복사본이 패키지 폴백보다 우선하며,
acpx 업그레이드는 이를 업데이트하지 않습니다. 작업당 새로운 HOME은 이를 다시 다운로드합니다(각각 수백
MB); 하나의 npm_config_cache를 공유하십시오. macOS에서 새로운 HOME은 또한 로그인 키체인을 숨깁니다:
claude 어댑터는 RUNTIME: Unable to validate model: Could not resolve authentication method로 실패합니다 - HOME을 유지하십시오. npx 캐시는 또한 오래된 빌드를 재사용합니다 -
~/.acpx/config.json에 정확한 어댑터 버전을 고정하십시오 (agents.<name>.argv). 고정은
어떤 모델 ID가 작동하는지 동결시키며, 변경하면 세션의 키가 변경됩니다 (세션 참조).
실행자는 사용자의 전역 명령 파일(claude의 ~/.claude/CLAUDE.md,
codex의 전역 AGENTS.md)을 상속받습니다. "편집 전에 물어보기"와 같은 규칙은 작업이 없는 상태로
질문에 헤드리스 턴을 끝냅니다 - 모든 브리프를 "지금 행동하라; 멈춰서 묻거나 질문으로 끝내지 마라"로 시작하십시오.
거기서 "아웃오브프로세스 실행자 사용"을 읽는 실행자는 동일한 체크아웃에 중첩된 acpx 차선을 실행할 수 있습니다 -
"너는 실행자다; 위임하지 마라"를 추가하십시오. 재실행 전에 오래된 결과 파일을 삭제하거나 이름을 바꾸십시오 (폴러가
오래된 것을 읽습니다), 그리고 병렬 차선에 고유한 임시 경로와 포트를 제공하십시오 - 별도의
작업 트리는 /tmp를 격리하지 않습니다.
또한 실행자는 실행자의 환경을 상속받으며, codex의 zsh는 모든 명령에 대해
$ZDOTDIR/.zshenv (기본 ~/.zshenv)를 다시 읽습니다 - 실행자에서 비밀을 해제해도
비밀을 차단하지 않으며, 셸이 출력하는 모든 것은 ~/.codex/sessions 아래의 롤아웃 파일에 들어갑니다.
agy / Antigravity
내장 acpx antigravity (0.17.1+)는 PATH에서 agy_acp_server.par를 실행하며,
Antigravity가 ~/.local/lib/antigravity-acp/에 설치하는 복사본은 PATH에 없습니다 -
단순 acpx antigravity는 Failed to spawn agent command: agy_acp_server.par와 함께 1로 종료됩니다. 해당 디렉토리를 PATH 앞에 추가하거나, agents.antigravity.argv를 설정하거나,
--agent <path>를 사용하십시오. 내장 gemini 에이전트는 공개 Gemini CLI입니다 -
다른 제품입니다. .par는 Antigravity 설치 또는 공식 ACP
레지스트리 아카이브에서 제공됩니다; 동일한 릴리스의 localharness_external 헬퍼 옆에 두십시오
(누락된 헬퍼는 Localharness not found.를 기록할 뿐 계속 진행합니다), 또는
ANTIGRAVITY_HARNESS_PATH를 가리키십시오. acpx도 agy update도 .par를 새로 고치지 않습니다:
해당 --version Build label:을
ACP 레지스트리와 비교하고
두 파일을 함께 교체하십시오 (설치된 헬퍼는 읽기 전용입니다 - 새 것을 복사하기 전에 rm -f로 제거하십시오).
D=/abs/real/dir # 반드시 존재해야 함: 루트는 realpath를 통해 해석됨
acpx --agent ~/.local/lib/antigravity-acp/agy_acp_server.par \
--cwd "$D" --model gemini-3.8-flash --approve-all --timeout 1800 \
exec "$D/brief.md를 실행하십시오. 보고서를 $D/report.md에 작성하십시오."
-
--approve-all은 필수입니다. 이것 없이는 모든 쓰기가 거부됩니다: 종료 5 (또는 종료 3으로의 지연),[done] end_turn이 여전히 출력되고 보고서가 없습니다. -
고정 선택 질문은
--approve-all아래에서도 종료 5로 프롬프트를 실패시킵니다 (마지막 줄Antigravity requested a user answer...) ---agent실행에서도 마찬가지입니다. acpx는 모든 에이전트의 고정 선택 질문을 이렇게 실패시킵니다 (PERMISSION_PROMPT_UNAVAILABLE); agy가 물리는 곳입니다. 사용자 선택이 필요 없는 브리프를 작성하십시오. -
ACP 세션이 광고하는 ID만 사용하십시오 - 의도적으로 잘못된
--model은 턴을 시작하지 않고Available models:를 출력합니다 (서버 1.4.5:gemini-4-argon,gemini-3.8-flash; ID에 노력이 포함된gemini-3.7-flash-{low,medium,high}ID는 사라졌습니다).agy models는 다른 목록입니다. Flash는 루브릭 기반 대량 작업에 적합하며 훨씬 빠르지만, 검토/버그 사냥 작업에서 실제 발견을 놓칩니다; 거기서는 더 강력한 모델을 사용하십시오. -
agy는 프롬프트 없이 형제 파일을 읽습니다 - 디렉토리를 공유하는 에이전트는 서로의 출력을 재현합니다. 에이전트당 하나의 디렉토리, 그리고 합의 번호를 믿기 전에 재실행의 체크섬을 확인하십시오.
-
인증:
<GEMINI_HOME>/antigravity-acp/settings.json에auth.type이 필요합니다 (일회성):mkdir -p ~/.gemini/antigravity-acp echo '{"auth":{"type":"oauth-personal"}}' > ~/.gemini/antigravity-acp/settings.json이것 없이: 즉시
[error] RUNTIME: Authentication required(종료 1). 이것이 있고 로그인한 적이 없으면:session/new는--timeout까지 브라우저 로그인을 차단합니다 (종료 3) - 한 번 대화식으로 로그인하십시오. 서버의 자격 증명은agyCLI의 것과 별개입니다: macOS Keychain (서비스gemini, 계정antigravity-acp), 또는 macOS가 아니거나AGY_ACP_FORCE_FILE_STORAGE=1일 때<GEMINI_HOME>/antigravity-acp/acp_token.json.GEMINI_HOME만으로는 macOS 자격 증명을 격리하지 않습니다. 자격 문제는 서버 측입니다 -gemini-api-key또는 GCP 프로젝트로 전환하여 "수정"하지 마십시오 (별도 청구, 수정 사항 아님). -
--agent와 위치 인자를 절대 전달하지 마십시오 - 종료 2. -
확인 프롬프트: 단순 응답을 요구하고 전체 로그를 읽으십시오. agy는 답변을 두뇌 아티팩트 파일로 라우팅하므로,
tail은 "도구 없음"과 "다른 곳에서 답변됨"을 구분할 수 없습니다. "파일을 생성하지 마십시오"를 추가하십시오. -
agy는 성공처럼 보이는 턴 내부에 MCP 실패를 숨깁니다 - 종료 0,
[done] end_turn, 그리고 전체 응답은MCP 서버 '<name>'이(가) 초기화에 실패했습니다: ...입니다.failed to initialize를 grep하십시오. -
exec를 선호하십시오. 체크포인트 중 서버 사망이 저장된 대화를 영구적으로 깨뜨리는 것으로 보고되었습니다 (could not find doneCh for checkpoint); 보고된 유일한 복구는~/.gemini/antigravity-acp/conversations/<id>.db를 삭제하는 것입니다.
Linux / NixOS
내장 에이전트는 필요한 --uid=를 자체적으로 추가합니다. NixOS는 추가로 CA
번들이 필요하므로, --agent (또는 agents.antigravity.argv)를 래퍼로 가리키십시오
(~/.local/bin/agy-acp-server):
#!/usr/bin/env bash
export SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
exec ~/.local/lib/antigravity-acp/agy_acp_server.par --uid= "$@"
SSL_CERT_FILE 없이 .par에 내장된 OpenSSL에는 유효한 CA 경로가 없습니다; 로컬
프록시는 502 Bad Gateway: Failed to connect to backend API를 보고하고 턴은 여전히
[done] end_turn으로 종료 0과 함께 끝납니다 (불변 규칙 5). 실제
CERTIFICATE_VERIFY_FAILED는 --alsologtostderr 아래에서만 나타납니다.
codex
D=/abs/dir
acpx --cwd "$D" codex sessions ensure --name work # 멱등적; -s는 생성 불가
acpx --cwd "$D" codex set model gpt-6-astra -s work
acpx --cwd "$D" codex set reasoning_effort high -s work
{ acpx --cwd "$D" --approve-all --timeout 5400 --suppress-reads \
codex -s work './brief.md를 실행하십시오. 보고서를 ./report.md에 작성하십시오.' && \
acpx --cwd "$D" codex sessions close work; } > run.log 2>&1 &
# 실패한 턴은 종료를 건너뜁니다 - -s work로 다시 프롬프트하여 복구한 다음 직접 종료하십시오
일회성: --model <id> exec --config-option reasoning_effort=low는 모델과
노력을 인라인으로 설정합니다.
- codex 어댑터 (
@agentclientprotocol/codex-acp)는^1.1.5에 떠 있습니다 - 동작은 acpx 업그레이드 없이 변경될 수 있지만, 2.x의 중대한 변경은 범위 밖입니다. 오래된 어댑터는 최신 모델 ID를 거부합니다:session/set_config_option에서[error] RUNTIME: Invalid params(종료 1), 또는 여전히[done] end_turn, 종료 0으로 끝나는 400model is not supported. 현재 것을 고정하십시오:{"agents":{"codex":{"argv":["npx","-y","@agentclientprotocol/[email protected]"]}}}. 정확한 고정은 그 안의 codex 바이너리를 여전히 떠 있게 합니다 (2.5.0은@openai/codex ^0.165.0에 의존). 계정에 모델이 없을 때도 동일한 증상이 현재 어댑터에서 발생합니다: 광고된 목록은 계정마다 다릅니다 - 차선 자체의 로그인 아래에서 사전 비행하십시오. - OpenAI의 콘텐츠 필터는 깨끗하게 끝나는 (
[done] end_turn, 종료 0) 무해한 턴을 죽입니다. 파일 이름, 주석 또는 프롬프트의 경쟁/스위프/악용/공격과 같은 어휘가 이를 트리거합니다. 완료를 믿기 전에 대화록의 꼬리를 읽으십시오; 동일한-s <name>으로 다시 프롬프트하여 복구하십시오 (컨텍스트는 재연결 실패 시를 제외하고 유지됩니다 - acpx는 조용히session/new로 폴백합니다).