Repository navigation
[Bug]: ocx CLI drops management 503 reason and hint, so operators cannot tell collision from ACL from down #2698
Description
Client or integration
Codex App / OpenCodex CLI
Area
CLI, Proxy and routing
Summary
Local operator CLI does not require a user-supplied API token, but when /api/* returns 503 the CLI prints only:
Error: management API unavailable
The server body already includes reason and hint. Operators cannot tell token collision (#2696) from ACL fail-close (#766) from a down proxy. ocx debug provider status is slightly better (Failed to read debug settings (503)) but still omits reason.
This is a CLI client bug in responseMessage. It remains useful after #2696 is fixed.
Reproduction
With the proxy healthy on /healthz and management plane 503:
ocx account list
curl -sS -H "Authorization: Bearer $(cat ~/.opencodex/admin-api-token)" \
http://127.0.0.1:10100/api/selected-modelsCLI:
Error: management API unavailable
curl (redacted):
{
"error": "management API unavailable",
"reason": "management credential conflicts with a data-plane credential",
"hint": "Set OPENCODEX_ADMIN_AUTH_TOKEN to bypass file-backed admin token ACL hardening"
}Version
2.33.0
Operating system
macOS 15.7.4
Logs or error output
src/cli/runtime-api.ts responseMessage only reads error / message / detail. It never appends reason or hint. runCliAction then prints Error: ${error.message}.
Live probe of 14 management commands on this host all collapsed to that one line (receipt in the reporter's notes; no secrets).
Checks
- I searched existing issues and documentation.
- I removed secrets, tokens, account details, request credentials, and personal data.
Related: #2696 (trigger), #819 (doctor/status omitting a credential; different owner). Do not fold into #2696.
Activity
lidge-jun commentedon Aug 26, 2026
리뷰 · 우선순위 72 / 80
설명
이 이슈는 관리면 503 응답에 이미 들어 있는
reason/hint를 CLI 가 버리고Error: management API unavailable만 찍는 문제를 보고합니다. 운영자는 토큰 충돌(#2696), ACL fail-close(#766), 프록시 다운을 구분할 수 없습니다. #2696 이 고쳐져도 다른 503 진단에 계속 필요합니다.current
dev의src/cli/runtime-api.tsresponseMessage(50-58줄) 는 body 에서error/message/detail문자열만 고릅니다.reason과hint는 읽지 않습니다. 서버가 내려 주는 충돌 사유를 curl 로는 보이는데 CLI 로는 안 보이는 상태와 정확히 맞습니다.심각도는 #2697(거짓 성공) 바로 아래입니다. 메시지 품질 버그이지만 로컬 설치 복구 시간을 크게 늘립니다. 버전 표기 차이는 경로와 무관합니다.
types.ts/config.ts분할로 닫을 대상이 아닙니다. 미리보기 배포는 계획에 없습니다.src/cli/runtime-api.ts:50 - responseMessage 가 error/message/detail 만 사용합니다
src/cli/runtime-api.ts:86 - RuntimeApiError 메시지가 잘린 reason/hint 없는 문자열입니다
경로/심볼 - 서버 503 body 의 reason/hint 는 CLI 에 전달되지 않습니다
경로/심볼 - ocx debug provider status 도 503 숫자만 보강할 뿐 reason 은 없습니다
경로/심볼 - #2696/#766 진단이 CLI 만으로는 불가능합니다
메인테이너의 판단이 필요한 지점
너의 추천
열어 두세요.
responseMessage가reason/hint를 붙이도록 고치고, 충돌 픽스처로 스냅샷 테스트를 넣으세요. #2696/#2697 과 같은 CLI 관리면 묶음으로 보면 좋습니다. 미리보기 배포는 계획에 없습니다.이 댓글은 grok-bot이 작성했습니다
Merge pull request #2775 from lidge-jun/codex/ocx-transport-honesty
fix(cli): stop the CLI reporting success for failed management calls
fix(cli): settle the 409 exit code against the pre-existing native-pr…
Merge pull request lidge-jun#2775 from lidge-jun/codex/ocx-transport-…
fix(cli): stop the CLI reporting success for failed management calls
fix(cli): settle the 409 exit code against the pre-existing native-pr…
Merge pull request lidge-jun#2775 from lidge-jun/codex/ocx-transport-…