Skip to content

README_EN.md

Latest commit

 

History

History
122 lines (86 loc) · 4.01 KB

README_EN.md

File metadata and controls

122 lines (86 loc) · 4.01 KB

Codex Agent

A managed runtime layer that lets OpenClaw operate Codex CLI reliably instead of depending on ad-hoc tmux automation.

Validated baseline

  • Validation date: 2026-03-24
  • Local Codex: codex-cli 0.116.0-alpha.10
  • Local OpenClaw: OpenClaw 2026.3.11
  • Local Codex defaults: gpt-5.4, xhigh reasoning, web_search = "live"

What this project now provides

  • Managed interactive Codex sessions via hooks/start_codex.sh
  • Managed one-shot codex exec runs via hooks/run_codex.sh
  • A runtime registry under ~/.openclaw/runtime/codex-agent
  • Explicit OpenClaw routing with stable --session-id
  • Detection of modern Codex startup blockers:
    • self-update prompt
    • directory trust prompt
  • Private logs and private monitor PID files
  • Sanitized completion previews in external notifications

Why the refresh was necessary

The repository had drifted badly:

  • state/version.txt was still on 0.104.0
  • docs still treated gpt-5.2 as the default model
  • removed Codex flags such as steer, collaboration_modes, and sqlite were still documented as current
  • OpenClaw session reset behavior was described incorrectly
  • startup monitoring did not recognize the current Codex update/trust blockers

Design stance

This repo learned from /Users/abel/project/claude-code-agent, but does not copy Claude-specific control flow.

Borrowed ideas:

  • stable session_key
  • stable openclaw_session_id
  • runtime session registry
  • explicit status/list tooling
  • wake dedupe

Not copied blindly:

  • Claude hook lifecycle
  • Claude permission callback model
  • Claude-specific handoff semantics

Main entry points

Recommended workflows

Interactive long-running work

bash hooks/start_codex.sh codex-agent-demo /absolute/workdir --full-auto

Inspect or attach:

bash runtime/list_sessions.sh
bash runtime/session_status.sh codex-agent-demo
tmux attach -t codex-agent-demo

Stop:

bash hooks/stop_codex.sh codex-agent-demo

Non-interactive automation

bash hooks/run_codex.sh /absolute/workdir --full-auto "Summarize the repository state."

Important upstream mismatch

OpenClaw’s latest docs describe a richer skills/ClawHub workflow, but the local openclaw skills command on this machine still exposes only list, info, and check.

This repo therefore documents two truths at once:

  • official docs for product direction
  • local CLI output for what is actually runnable today

When those disagree, installation and operational docs prefer the locally verified path.

Setup

See INSTALL.md.

The three quickest verification commands are:

codex --version
openclaw --version
bash tests/regression.sh

Primary references