ray
55 lines
2.0 KiB
Markdown
55 lines
2.0 KiB
Markdown
# Codex CLI — Detailed Integration Guide
|
|
|
|
[Codex](https://github.com/openai/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
|
|
|
|
```bash
|
|
terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)
|
|
```
|
|
|
|
For scratch work (Codex needs a git repo):
|
|
```bash
|
|
cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'
|
|
```
|
|
|
|
## Background Mode (Long Tasks)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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 |
|