문제 해결
설치는 정상처럼 보이지만 실제 OMX 실행이 실패할 때 확인할 경계
omx setup이나 omx doctor는 통과하지만 실제 Codex 요청이 실패할 때 이 페이지를 보세요.
설치 상태와 실행 상태
omx doctor는 prompts, skills, config, hooks, AGENTS scaffolding, runtime prerequisites 같은 local OMX surface를 확인합니다. 하지만 활성 Codex profile이 인증되어 있고 실제 model request를 완료할 수 있다는 뜻은 아닙니다.
OMX를 실행할 같은 shell, HOME, CODEX_HOME, project directory에서 smoke test를 돌리세요.
codex login status
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"| 확인 | 증명하는 것 |
|---|---|
omx doctor green | local OMX wiring이 정상처럼 보입니다. |
codex login status green | 활성 Codex profile이 login state를 볼 수 있습니다. |
omx exec ...가 OMX-EXEC-OK 반환 | auth, provider routing, execution, cwd 가정이 함께 맞습니다. |
흔한 실패 모드
| 증상 | 확인 |
|---|---|
401 Unauthorized, bearer auth 누락, 잘못된 API key | OMX를 띄우는 shell의 HOME/CODEX_HOME이 같은지 확인합니다. |
| proxy/gateway 인증 실패 | local OpenAI-compatible proxy를 쓰면 활성 ~/.codex/config.toml의 openai_base_url을 확인합니다. |
AGENTS.md는 있지만 doctor가 OMX contract 누락을 보고 | omx setup --scope user --merge-agents 또는 project scope로 다시 병합합니다. |
.omx/ 또는 .beads/ write 실패 | root-owned, owner mismatch, non-writable 파일을 확인합니다. omx doctor --force는 repo root가 현재 사용자 소유일 때만 자동 복구합니다. |
Team resume 또는 doctor --team이 죽은 tmux state 참조 | omx team status <team>과 tmux ls를 먼저 확인하고, 폐기된 team이면 omx team shutdown <team> --force --confirm-issues, 그 뒤 omx cancel을 실행합니다. |
| tmux 안에서 Shift+Enter가 줄바꿈 대신 submit | tmux show -gv extended-keys, `tmux info |
Deprecated Explore Surface
omx explore는 hard-deprecated입니다. read-only repo lookup은 일반 Codex inspection tool/subagent를 쓰고, shell-native evidence나 tmux-pane summary가 필요하면 omx sparkshell -- <command>를 쓰세요.