Codex CLI (clawcode)

Use OpenAI Codex as an external coding agent when the user wants Codex specifically.

Do not confuse these entry points (they are not interchangeable):

Entry	Role
/codex-cli (TUI slash)	One-shot probe or command via codex_cli_bridge: merged stdout/stderr, not a PTY session and not multi-turn TUI control. Default args often --version.
bash	One-shot shell in agent turns, e.g. codex exec '…'.
terminal + process (Agent tools)	Multi-turn driving of Codex: terminal with background=true (and pty=true on POSIX with clawcode[terminal-pty]), then process for poll / submit / kill. Codex expects a git repo; for scratch dirs use mktemp -d && git init. Windows local PTY is limited—full TUI automation use WSL/Linux.

Optional: pip install 'clawcode[terminal-pty]' for ptyprocess on POSIX.

Prerequisites

• Install Codex: npm install -g @openai/codex (command name codex on PATH).
• Configure OpenAI credentials per Codex docs (API key / auth).
• Git repository — many Codex flows refuse to run outside a repo; use a temp dir + git init for greenfield scratch.

When to use

• User asks for Codex or codex explicitly.
• You need a bounded task: prefer codex exec '...' via bash in the project workspace.
• Quick install check: /codex-cli after /claw (default codex --version); same terminal stack as /claude-cli / /opencode-cli.

clawcode-specific capabilities

Goal	What to use
Quick probe	/codex-cli only—single run, not multi-run TUI.
One-shot exec	bash or terminal foreground: codex exec 'task' with working_directory in a git repo.
Long / background	terminal (background=true, pty=true where supported) + process. Optional check_interval on terminal for TUI completion notifications (see CLAW_SUPPORT_MAP.md).

One-shot examples (foreground)

terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)

Scratch with new repo:

terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)

Background mode

terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")
process(action="submit", session_id="<id>", data="yes")
process(action="kill", session_id="<id>")

Key flags (Codex upstream)

Flag	Effect
exec "prompt"	One-shot run, exits when done
--full-auto	Sandboxed; auto-approves file changes in workspace
--yolo	No sandbox (dangerous; use with care)

Rules

1. Prefer pty=true for interactive Codex sessions on POSIX; without PTY many CLIs misbehave.
2. Respect git repo requirements; document when you create a throwaway repo.
3. /codex-cli does not replace terminal/process for long interactive work.