63 lines
2.7 KiB
Plaintext
63 lines
2.7 KiB
Plaintext
---
|
|
title: Codex
|
|
description: OpenAI's Codex CLI. Full session resume and native JSONL event stream.
|
|
---
|
|
|
|
import { Accordions, Accordion } from "fumadocs-ui/components/accordion";
|
|
|
|
<div style={{ display: "flex", alignItems: "center", gap: "0.75rem", margin: "0.5rem 0 1.25rem" }}>
|
|
<Logo name="codex" size={28} />
|
|
<span style={{ fontSize: "0.8125rem", color: "var(--color-fd-muted-foreground)" }}>Slot: <code>agent</code> · Name: <code>codex</code> · Binary: <code>codex</code></span>
|
|
</div>
|
|
|
|
[OpenAI Codex CLI](https://github.com/openai/codex) is a terminal coding agent from OpenAI. AO hooks into it via PATH wrappers and reads its native session JSONL for activity + cost.
|
|
|
|
<PlatformSupport macos="full" linux="full" windows="full" />
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install -g @openai/codex
|
|
```
|
|
|
|
## Use
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
agent: codex
|
|
```
|
|
|
|
No plugin-level config.
|
|
|
|
## How it works
|
|
|
|
- **Launch:** `codex` runs inside the worktree. AO sets `CODEX_DISABLE_UPDATE_CHECK=1` to keep the agent quiet about updates mid-session.
|
|
- **Activity tracking:** Codex writes session events to `~/.codex/sessions/YYYY/MM/DD/<id>.jsonl`. AO reads the last entry to determine `active/ready/idle/waiting_input/blocked`.
|
|
- **PR + git tracking:** AO installs wrappers at `~/.ao/bin/gh` and `~/.ao/bin/git`. When Codex runs `gh pr create`, the wrapper records the PR number in the session metadata.
|
|
- **Session resume:** `codex resume <threadId>` — AO stores the thread id in session metadata and replays it.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Set by AO | Purpose |
|
|
|---|---|---|
|
|
| `AO_SESSION_ID` | ✓ | AO session id |
|
|
| `AO_ISSUE_ID` | ✓ | Issue identifier |
|
|
| `PATH` | ✓ | Prepends `~/.ao/bin` for the wrappers |
|
|
| `GH_PATH` | ✓ | Absolute path to the real `gh`, used by the wrapper |
|
|
| `CODEX_DISABLE_UPDATE_CHECK` | ✓ (`1`) | Skip version check |
|
|
|
|
OpenAI API credentials come from wherever `codex` reads them — AO doesn't set them.
|
|
|
|
## Troubleshooting
|
|
|
|
<Accordions>
|
|
<Accordion title="`codex` not found after install">
|
|
npm-global install sometimes misses the PATH. Run `which codex` — if empty, add your global bin (`npm config get prefix` + `/bin`) to PATH.
|
|
</Accordion>
|
|
<Accordion title="Dashboard activity stuck on `idle`">
|
|
AO reads `~/.codex/sessions/`. If the date-sharded path doesn't match your clock (e.g. Docker container with wrong TZ), sessions look stale — align the clocks.
|
|
</Accordion>
|
|
<Accordion title="PR created but dashboard doesn't know">
|
|
The PATH wrapper writes session metadata on `gh pr create`. If `gh` was invoked with an absolute path (bypassing the wrapper) AO won't see it. `ao session claim-pr <pr> <sessionId>` fixes this retroactively.
|
|
</Accordion>
|
|
</Accordions>
|