ray
2.0 KiB
Codex CLI — Detailed Integration Guide
Codex is OpenAI's autonomous coding agent CLI. This reference covers auth, edge cases, and gateway-specific pitfalls.
Auth
Codex can use OPENAI_API_KEY or OAuth. For Hermes itself, model.provider: openai-codex uses Hermes-managed Codex OAuth from ~/.hermes/auth.json after hermes auth add openai-codex. For standalone CLI, a valid OAuth session may live under ~/.codex/auth.json — do not treat a missing OPENAI_API_KEY alone as proof that Codex auth is missing.
One-Shot Tasks
terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)
For scratch work (Codex needs a git repo):
cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'
Background Mode (Long Tasks)
terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
# Returns session_id — monitor with process(action="poll"|"log")
Hermes Gateway Caveat
When invoking Codex CLI from a gateway/service context (Telegram-driven sessions), Codex workspace-write sandboxing may fail due to bubblewrap/user-namespace restrictions. Prefer:
codex exec --sandbox danger-full-access "<task>"
Use process boundaries as the safety layer: explicit workdir, clean git status before launch, narrow task prompts, git diff review, targeted tests.
Parallel Issue Fixing with Worktrees
# Create worktrees
git worktree add -b fix/issue-78 /tmp/issue-78 main
# Launch Codex in each
terminal(command="codex --yolo exec 'Fix issue #78'", workdir="/tmp/issue-78", background=true, pty=true)
Key Flags
| Flag | Effect |
|---|---|
exec "prompt" |
One-shot execution, exits when done |
--full-auto |
Sandboxed but auto-approves file changes |
--yolo |
No sandbox, no approvals (fastest, most dangerous) |
--sandbox danger-full-access |
No sandbox; useful when bubblewrap fails |