# Codex

> Delegate coding to OpenAI Codex CLI (features, PRs).

- Skill: `openclaw-cn-dev/codex` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add openclaw-cn-dev/codex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openclaw-cn-dev/codex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: openclaw-cn-dev (https://skillmd.com/u/openclaw-cn-dev)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/openclaw-cn-dev/codex

---


# Codex CLI

Delegate coding tasks to [Codex](https://github.com/openai/codex) via the Hermes terminal. Codex is OpenAI's autonomous coding agent CLI.

## When to use

- Building features
- Refactoring
- PR reviews
- Batch issue fixing
- **Browser automation** — web scraping, 自媒体运营, form filling, data extraction from web apps (Codex's Playwright-based `browser`/`chrome` plugins are faster and more stable than Hermes' built-in browser stack)

Requires the codex CLI and a git repository.

## Prerequisites

- Codex installed: `npm install -g @openai/codex`
- OpenAI auth configured: either `OPENAI_API_KEY` or Codex OAuth credentials
  from the Codex CLI login flow
- **Must run inside a git repository** — Codex refuses to run outside one
- Use `pty=true` in terminal calls — Codex is an interactive terminal app

For Hermes itself, `model.provider: openai-codex` uses Hermes-managed Codex
OAuth from `~/.hermes/auth.json` after `hermes auth add openai-codex`. For the
standalone Codex CLI, a valid CLI OAuth session may live under
`~/.codex/auth.json`; do not treat a missing `OPENAI_API_KEY` alone as proof
that Codex auth is missing.

### Recovering a broken npm install

If `codex --version` throws `Missing optional dependency @openai/codex-darwin-arm64`,
the npm install lost its platform-specific binary. Reinstall:

```bash
npm install -g @openai/codex@latest
```

This fixes the missing optional dependency without any additional flags.

### Cron/Sandboxed Upgrade Workflow (Permission Issues)

When upgrading Codex in a cron job or sandboxed environment:
1. **Global npm install may fail with EACCES** — `/usr/local/lib/node_modules` requires sudo
2. **sudo doesn't work in cron** — no terminal for password input
3. **华哥's codex lives at `~/.local`**, NOT the npm global default — always use this prefix

**Verified Workflow (2026-07-17) — direct local install without sudo:**
```bash
# Direct install to the exact prefix where codex is already installed
# This avoids any copying afterward
npm install -g @openai/codex --prefix /Users/hua/.local

# Verify
/Users/hua/.local/bin/codex --version
```

**Legacy fallback** (if prefix method times out or fails):
```bash
# Install to temp prefix then copy
npm install -g @openai/codex --prefix ~/.npm-global
cp -r ~/.npm-global/lib/node_modules/@openai/codex /Users/hua/.local/lib/node_modules/@openai/
```

**Path pitfalls to avoid**:
- Cron jobs run under Hermes profile home (`~/.hermes/profiles/<name>/home/`), but the real codex binary lives at `/Users/hua/.local/bin/codex`
- **Never use `~`** in paths during cron — it expands to the profile home, not the user home
- Always use absolute paths: `/Users/hua/.local/`, not `~/.local/`
- **npm can timeout** — if the install hangs after 60s, try again with a clean npm cache

## China Login Blocked (2026-07-11)

OpenAI blocks OAuth login from China IPs:
```
"error": {"code": "***SECRET***"}
```

**Workaround**: Codex **does not need OpenAI login** when using custom model providers (DeepSeek via LLM Gateway). All model calls go through `127.0.0.1:18888` → DeepSeek API. The blocked login only prevents:
- Using OpenAI's own models (GPT-4, etc.)
- OAuth-based MCP servers (Linear, Figma)
- Marketplace browsing directly

The 15 locally cached plugins work fine without login. OAuth-dependent ones (Linear, Figma) show auth errors but don't block Codex.

### API Key Login (Alternative)
Codex supports API key login: `codex login` with `sk-...` key. Project keys (`sk-proj-...`) need a project ID header. Regular API keys (`sk-...`) work directly. Free tier supports `gpt-4o-mini` and other models.

## Gateway Debugging — Lessons from 2026-07-11 DeepSeek Migration

When the Gateway returns 502 for Codex but direct HTTP tests pass, check:

### 1. Path matching: `/openai/v1/responses` vs `/openai/responses`
Codex may send either path depending on version. Gateway must match both:
```python
is_responses = request.path.startswith("/openai/responses") or request.path.startswith("/openai/v1/responses")
```

### 2. Volcengine URL correction must check backend URL, not route name
```python
# WRONG: "volc" in which — "which" is "primary"/"fallback", never contains "volc"
# RIGHT:
if is_responses and "volces.com" in backend["url"]:
    rest = "/chat/completions"  # volcengine doesn't use /v1/ prefix
```

### 3. Responses API `input` field translation
When `input` is a string (single-turn), wrap it in a proper messages list:
```python
if isinstance(input_val, str):
    body_json["messages"] = [{"role": "user", "content": input_val}]
```
Otherwise DeepSeek receives `"messages": "some string"` and returns 400.

### 4. DeepSeek model names are strict
DeepSeek API accepts ONLY `deepseek-v4-pro` or `deepseek-v4-flash` — no volcengine suffixes (`-260425`). Passing `***SECRET***` to DeepSeek returns 400.

### 5. Gateway process can hang silently
Symptoms: health endpoint returns 200, but no new requests logged. Process shows 0% CPU.
- Kill the process, unload launchd plist, start fresh with brew Python 3
- Launchd double-launch can cause state corruption
- `launchctl unload` the plist before manual restart to prevent auto-respawn

### 6. Python 3.14 + aiohttp 3.14.1 is the current runtime
Gateway run command:
```bash
/opt/homebrew/bin/python3 ~/.hermes/scripts/llm_gateway.py --port 18888
```
System Python 3.9 lacks aiohttp — always use brew Python.

## Current Setup (华哥's machine, as of 2026-08-08)

### LLM Gateway with Responses API SSE Translation (v0.144.1)

Codex v0.144.1 uses `wire_api = "responses"` which expects OpenAI Responses API format with SSE streaming. The LLM Gateway (`~/.hermes/scripts/llm_gateway.py`) provides full bidirectional SSE streaming translation:

**Request translation** (Responses → Chat Completions):
- `input` → `messages`, `max_output_tokens` → `max_tokens`
- Role: `developer` → `system`
- Content type: `input_text` → `text`
- Forces `stream: true` for SSE delivery

**SSE event translation** (DeepSeek SSE → Responses API events):
- `response.created` — session start with response ID
- `response.output_item.added` — before first text delta
- `response.output_text.delta` — per-token text streaming
- `response.completed` — final with output array and usage (prompt_tokens→input_tokens)

Gateway routes `/openai/responses` → `/v1/chat/completions` (DeepSeek) or `/chat/completions` (Volcengine).

### Breaking Changes in v0.142.5

1. **`wire_api` must be `"responses"`** — `"chat_completions"` causes config load failure: `unknown variant 'chat_completions', expected 'responses'`. Update all provider blocks.
2. **Plugin command changed** — `codex plugin install <name>` removed. Use `codex plugin add <name>@<marketplace>` instead.
3. **Some plugins removed** — `browser`, `chrome`, `computer-use` no longer available in `openai-api-curated` marketplace.

### Connection (as of 2026-07-11)

Codex CLI v0.144.1 connects through the **LLM Gateway** (port 18888) which now routes **DeepSeek as primary** (Volcengine Agent Plan quota exceeded 7/11, resets 7/13):

**`~/.codex/config.toml` (current, 2026-07-17 — via LLM Gateway, NO CC Switch):**
```toml
model_provider = "custom"
model = "deepseek-v4-pro"          # via LLM Gateway → DeepSeek API (primary)
model_reasoning_effort = "high"
disable_response_storage = true
wire_api = "responses"

[model_providers]
[model_providers.custom]
name = "hermes_gateway"
base_url = "http://127.0.0.1:18888/openai"       # NO /v1 suffix — Codex appends /v1/responses
wire_api = "responses"
requires_openai_auth = false
```

Gateway routes (in `~/.hermes/scripts/llm_gateway.py`): `/openai` primary→DeepSeek, fallback→Volcengine Agent Plan.

### Active Model
- **`deepseek-v4-pro`** — the ONLY model name that works with DeepSeek API directly. No `-260425` suffix (that's a volcengine-specific model ID). DeepSeek API accepts `deepseek-v4-pro` or `deepseek-v4-flash`.
- When volcengine quota resets (7/13), volcengine models become available again: `***SECRET***`, `deepseek-v4-pro-260425`, `glm-5.2`, etc.
- **Model capabilities**: See `references/volcengine-model-capabilities.md` for which models support vision input, image generation, and code. DeepSeek = text-only; doubao/GLM = vision; seedream = image gen.

### Installed Plugins (17, as of 2026-08-08)

v0.147.0 auto-discovers plugins from 4 marketplace cache directories:

**openai-api-curated (7):**
| Plugin | Purpose |
|--------|---------|
| `superpowers` | Extended capabilities |
| `github` | GitHub integration |
| `coderabbit` | Code review |
| `build-web-apps` | Web app development |
| `linear` | Project management (needs OAuth) |
| `sentry` | Error monitoring |
| `figma` | Design integration (needs OAuth) |

**openai-bundled (4):**
| Plugin | Purpose |
|--------|---------|
| `browser` | Browser automation |
| `chrome` | Chrome control |
| `computer-use` | Desktop automation |
| `visualize` | Data visualization |

**openai-primary-runtime (5):**
| Plugin | Purpose |
|--------|---------|
| `documents` | Document handling |
| `pdf` | PDF processing |
| `spreadsheets` | Spreadsheet operations |
| `presentations` | Presentation tools |
| `template-creator` | Template generation |

**sisyphuslabs (1):**
| Plugin | Purpose |
|--------|---------|
| `omo` | Model orchestration |

No manual `codex plugin install/add` needed — plugins auto-discovered from marketplace directories on each run.

**Unused (not in cache):** `latex`, `record-and-replay`, `remotion`, `game-studio`, `expo`, `render`, `nvidia`, `circleci`, etc. — available in marketplace but not cached locally.

### AGENTS.md (as of 2026-08-08)
Project-level instructions at `~/.codex/AGENTS.md`:
- Chinese primary language, English code comments
- Current model: `deepseek-v4-pro` via local Gateway `127.0.0.1:18888`
- 17 plugins across 4 marketplace cache directories (api-curated, bundled, primary-runtime, sisyphuslabs)
- Tools: GitHub CLI, Computer Use, Browser automation, LLM Gateway

### Maintenance (玉芬 managed)
Codex is under 玉芬's autonomous maintenance with 3 cron jobs:
- **Daily 9:00** — version check + auto-upgrade (see Cron/Sandboxed Upgrade Workflow)
- **Daily 10:00** — full status sync: version check, plugin audit (via `ls ~/.codex/plugins/cache/*/`), then GitHub sync via `~/.hermes/scripts/codex_github_sync.sh` (not the legacy `sync_codex_repo.sh`)
- **Weekly Mon 9:00** — full evolution scan: plugins, config, Gateway, AGENTS.md, new features

**Version check pattern for cron jobs (verified 2026-07-17):**
```bash
# 1. Get current version — use absolute path for cron safety
OLD=$(/Users/hua/.local/bin/codex --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')

# 2. Get latest npm version
NEW=$(npm view @openai/codex version 2>&1)

# 3. Compare and upgrade if needed
if [ "$OLD" != "$NEW" ] && [ -n "$OLD" ] && [ -n "$NEW" ]; then
  # Use direct local prefix install (verified method, no copying needed)
  npm install -g @openai/codex --prefix /Users/hua/.local
  
  # Verify and report upgrade
  VERIFIED=$(/Users/hua/.local/bin/codex --version 2>&1 | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')
  echo "📦 Codex 已升级：$OLD → $VERIFIED。插件保持原样，如需更新插件请手动 codex plugin update。"
fi
```

**Daily Status Sync — TWO scripts, two purposes (2026-08-08 clarified):**

| Script | Purpose | GitHub Push | Cache Dir |
|--------|---------|:-----------:|-----------|
| `~/.hermes/scripts/codex_github_sync.sh` | **Real GitHub sync** (hourly cron) | ✅ `git@github.com:openclaw-cn-dev/yuxin-skills.git` | `/tmp/yuxin-skills-codex-sync/` |
| `~/6-产品研发/22-出图智能体训练/sync_codex_repo.sh` | Local backup only | ❌ local-only | `~/codex-workspace/yuxin-skills/` |

The hourly sync script calls `codex_self_evolution.py --sync-only`, which:
1. Version check → 2. Plugin validation (cache dirs) → 3. Copy AGENTS.md, config.toml (脱敏), skills/yuxin-*, plugins.json, STATUS.md → 4. Git commit + push

**Daily full cron** should run BOTH: version check + plugin audit first, then the hourly sync script for the GitHub push. The `sync_codex_repo.sh` in the 出图项目 is a legacy local-only script — it cannot push to GitHub because the `~/codex-workspace/` clone has no remote configured.

**PATH requirement for cron contexts (2026-08-08):**
- `codex` lives at `/Users/hua/.local/bin/codex` — NOT on default cron PATH
- Always prefix: `export PATH="$HOME/.local/bin:$PATH"` or use absolute path `/Users/hua/.local/bin/codex`
- The hourly sync script (`codex_github_sync.sh`) runs via Hermes venv Python, which handles PATH internally

**Plugin cache pitfall (2026-07-15, confirmed 2026-08-08):**
- Expected cache path `~/.codex/plugins/cache/openai-api-curated/` may be empty or not exist when not logged in
- `codex plugin list` without login = ALL plugins show "not installed" — this is the marketplace install state, NOT the cache reality
- AGENTS.md records 17 plugins across 4 cache dirs: openai-api-curated (7), openai-bundled (4), openai-primary-runtime (5), sisyphuslabs (1)
- **Real plugin status must be verified with `ls ~/.codex/plugins/cache/*/`**, not `codex plugin list`

**npm path mismatch (codex doctor finding):**
- Running codex: `/Users/hua/.local/lib/node_modules/@openai/codex`
- npm global root: `/usr/local/lib/node_modules/@openai/codex`
- This causes "npm install -g would update a different install" warning in `codex doctor`
- Workaround: Always use the local prefix install method (see Cron/Sandboxed Upgrade Workflow)

**GitHub sync fallback:**
- When GitHub SSH auth isn't configured, `sync_codex_repo.sh` initializes a local git repo at `~/codex-workspace/yuxin-skills/` without remote
- Status reports are saved locally even if remote push fails
- For actual GitHub push, use the hourly sync script which targets `/tmp/yuxin-skills-codex-sync/` with a pre-configured SSH remote

Update AGENTS.md after any model/provider/plugin change. Keep the `codex` skill in sync.

### MCP Servers (3)
Configured in `~/.codex/arkcli.config.toml`:
- **DataPro Search** — Volcengine data search
- **Echo Search** — General search engine
- **OpenViking Control Plane** — Cloud resource management

## Hermes ↔ Codex Collaboration

### 生产代码优化实战流程（2026-08-16 验证）

对正式项目（非临时 scratch）用 codex 做代码优化，稳定流程：

1. **任务描述写到文件**，避免 shell 转义（中文 + 引号 + 冒号等特殊字符）：`write_file /tmp/codex_task.txt`。内容必须自包含：背景 → 现状问题（编号列出）→ 具体任务（编号，含"只改哪些文件、不破坏哪些"）→ 要求（注释英文/日志中文/验证命令）→ 完成后报告什么。
2. **codex exec 读文件执行**（后台 + 完成通知）：
   ```bash
   terminal(command='cd <项目> && /Users/hua/.local/bin/codex exec --sandbox workspace-write "$(cat /tmp/codex_task.txt)"', background=true, notify_on_complete=true)
   ```
3. **实测验证 self-report**（codex 报告"已完成 + 测试全通过"不算数，必须亲自验）：
   - 读改动后的代码，确认逻辑真实落地（不是口头描述）
   - 实际启动/运行：`curl` health、调接口、看返回
   - 语法/import：`python3 -c "import ast; ast.parse(open('x.py').read())"` 和 `import` 模块验证

### 社交平台发布集成（codex_bridge 模式，2026-08-16）

华哥验证 Codex 浏览器插件做社交平台发布（登录/填表/发布）有优势。HG-运营中枢 用 `codex_bridge.py` 集成：FastAPI 服务接收发布任务 → `asyncio.subprocess` 调 `codex exec` 浏览器插件真实发布。任务提示词含平台名/创作者中心发布 URL/标题/正文/标签 + "登录→填表→发布→返回确认"，结果用 `PUBLISH_OK|平台|链接` / `PUBLISH_FAIL|原因` 格式约束。关键前提：**codex 必须切到 vision 模型**（doubao-seed-2-0-pro / glm-5.2-pro），text-only 的 deepseek 浏览器插件"看不见"页面无法真实操作。详见 `hg-ops-platform` 技能。

Use `delegate_task` to hand off coding tasks to Codex:

```python
# In Hermes, delegate a coding task to Codex
delegate_task(
    goal="Add dark mode toggle to settings page",
    context="Project at ~/project. Use codex exec with --sandbox workspace-write",
    toolsets=["terminal", "file"]
)
```

Or directly via terminal:
```bash
terminal(command="codex exec --sandbox workspace-write 'Add dark mode toggle'", workdir="~/project")
```

## Browser Automation via Codex

**When Hermes browser tools are too slow or unstable, delegate to Codex.** Codex's `browser` and `chrome` plugins (Playwright-based) are faster, handle dynamic pages better, and have built-in bot-detection evasion.

### Vision Model Requirement (critical)

Browser plugins need a model that can **see** screenshots. Text-only models can drive the browser but can't parse visual page state — effectively useless for real web automation.

| Model | Vision | Browser usable? |
|-------|:------:|:---------------:|
| `doubao-seed-2-0-pro` | ✅ | ✅ Best domestic option |
| `glm-5.2-pro` | ✅ | ✅ Long context + vision |
| OpenAI GPT-4o | ✅ | ✅ Native integration, needs proxy from China |
| `MiniMax-M2.7` | ❌ | ❌ Current model — browser plugins load but can't see |
| `deepseek-v4-pro/flash` | ❌ | ❌ Text-only |
| `doubao-seed-2-0-code-preview` | ❌ | ❌ Code-focused, no vision |

### Three paths to activate

| Path | Model | Setup | Status |
|------|-------|-------|:------:|
| A | OpenAI GPT-4o | API key (`sk-...`) + proxy via Gateway | 华哥说可以申请帐号 |
| B | Volcengine doubao-pro | Existing Agent Plan, switch model | 配额可能紧张 |
| C | GLM-5.2 | 智谱 API key | 需单独申请 |

### Usage pattern

```bash
# Delegate browser task to Codex (vision model required)
terminal(command="codex exec --sandbox workspace-write \
  'Go to https://creator.douyin.com, log in, and post this video draft'",
  workdir="~/codex-workspace", background=true, pty=true)
```

### Checking if Codex browser is ready

```bash
# 1. Confirm browser plugin exists
ls ~/.codex/plugins/cache/openai-bundled/browser/

# 2. Confirm model supports vision
grep '^model' ~/.codex/config.toml
# Must be doubao-seed-2-0-pro / glm-5.2-pro / or an OpenAI vision model
# MiniMax-M2.7 or deepseek = text-only = browser won't work visually

# 3. Quick smoke test with vision model
codex exec --skip-git-repo-check \
  "Navigate to https://example.com and tell me what the page title is" \
  2>&1 | tail -5
```

When the user says "I updated Codex", run these checks:

```bash
# 1. Check config loads without error
codex plugin list 2>&1 | head -3

# 2. If "unknown variant 'chat_completions'" → wire_api must be "responses"
grep -n 'chat_completions' ~/.codex/config.toml && \
  echo "⚠️  Change all 'chat_completions' to 'responses'"

# 3. Verify installed plugins
ls ~/.codex/plugins/cache/openai-api-curated/

# 4. LLM Gateway health
curl -s http://127.0.0.1:18888/health

# 5. Test a simple Codex call (using doubao, non-reasoning for speed)
echo "hello" | codex exec --skip-git-repo-check --sandbox workspace-write \
  -c model=***SECRET*** 2>&1 | tail -3
```

Common post-update fixes:
- `wire_api = "chat_completions"` → `"responses"` (most common breakage)
- Reinstall plugins: `codex plugin add <name>@openai-api-curated`
- `browser`/`computer-use` plugins unavailable → removed from marketplace
- Gateway using old code → `pkill -f llm_gateway && bootout launchd` + restart
- 404 on volcengine → check Gateway log for URL with extra `/v1/` prefix

Codex supports custom model providers via its `config.toml` and an optional companion `arkcli.config.toml` (for Volcengine/Ark CLI setups).

### Ark CLI (Volcengine Agent Plan)

Configure Codex to use a Volcengine Agent Plan (火山引擎智能体计划) model:

**`~/.codex/arkcli.config.toml`:**
```toml
model = "deepseek-v4-flash-260425"        # or deepseek-v4-pro-260425
model_catalog_json = "/Users/hua/.codex/arkcli.models.json"
model_context_window = 1048576            # 1M tokens
model_provider = "arkcli-agent-plan"

[model_providers]
  [model_providers.arkcli-agent-plan]
    base_url = "https://ark.cn-beijing.volces.com/api/plan/v3"
    experimental_bearer_token = "ark-xxxxx-xxxxx"
    name = "Volcano Engine (Agent Plan)"
    wire_api = "responses"
```

**`~/.codex/config.toml`** (primary config):
```toml
model_provider = "custom"
model = "deepseek-v4-flash-260425"
model_reasoning_effort = "high"
disable_response_storage = true
wire_api = "responses"

[model_providers]
[model_providers.custom]
name = "ark_agentplan"
base_url = "http://127.0.0.1:15721/v1"    # local proxy
wire_api = "responses"
requires_openai_auth = true
experimental_bearer_token = "PROXY_MANAGED"
```

**Model catalog** (`~/.codex/arkcli.models.json`) lists available models. Common ones:
- `deepseek-v4-flash-260425` — fast, 1M context
- `deepseek-v4-pro-260425` — stronger reasoning, 1M context
- `***SECRET***` — code-focused, 262K context

**Auth check:** `codex login status` shows whether you're logged in via API key or OAuth.

**Switching models:** Edit `model = "..."` in both `config.toml` and `arkcli.config.toml`, then restart Codex. The model must exist in the catalog JSON.

### Direct Connection (Bypass CC Switch) — Current

Codex connects directly to Volcengine Agent Plan (no CC Switch proxy).
When the user manually updates Codex, check `wire_api` values first — they're the most common breakage.

### LLM Gateway Management (port 18888)

The Gateway runs as a background process. Update code then restart:

```bash
# Kill and restart with brew Python (system Python 3.9 lacks aiohttp)
pkill -f llm_gateway.py
# IMPORTANT: Ensure launchd service is disabled first or it will auto-respawn
launchctl bootout gui/$(id -u)/com.yuxin.llm-gateway 2>/dev/null || true
/opt/homebrew/bin/python3 ~/.hermes/scripts/llm_gateway.py --port 18888 &

# Verify
curl -s http://127.0.0.1:18888/health
```

### Model Switching (DeepSeek ↔ Volcengine)

Use `~/.hermes/scripts/switch_model.py` to switch ALL components at once:

```bash
python3 ~/.hermes/scripts/switch_model.py deepseek     # 切 DeepSeek
python3 ~/.hermes/scripts/switch_model.py volcengine   # 切火山引擎
python3 ~/.hermes/scripts/switch_model.py status       # 看当前状态
```

This updates: Gateway routes + all 7 Hermes profiles + Codex config.toml + arkcli.models.json. Codex requires restart after switch.

The Gateway has an admin API for manual route control:
```bash
curl "http://127.0.0.1:18888/admin/switch?action=status"     # check
curl "http://127.0.0.1:18888/admin/switch?action=flip"       # swap primary↔fallback
curl "http://127.0.0.1:18888/admin/switch?action=to-primary" # force primary
```

**launchd pitfall**: A legacy launchd service (`com.yuxin.llm-gateway`) auto-respawns on system Python 3.9 (missing aiohttp). Always `bootout` before manual restart. The plist has been updated to use `/opt/homebrew/bin/python3` — reload with `launchctl bootstrap` when ready.

### CC Switch Proxy Troubleshooting (Fallback)

When Codex is routed through **CC Switch** (a local proxy that intercepts API calls), the proxy's SQLite database overrides whatever model you configure in Codex's `config.toml`. If CC Switch's stored model doesn't support the `/responses` endpoint, Codex fails with:

```
unexpected status 404 Not Found: CC Switch local proxy failed while handling Codex endpoint /responses.
Provider: 火山Agentplan; model: ark-code-latest;
upstream_status: HTTP 404;
cause: The requested model does not support the coding plan feature.
```

**Root cause:** CC Switch stores a `settings_config` JSON blob in its `providers` table with a hardcoded `model = "ark-code-latest"` that overrides the user's Codex config. The model `ark-code-latest` does not support the `/responses` API (coding plan feature).

**Quick fix** — update the model in CC Switch's SQLite database:

```bash
# 1. Find the Codex provider (dynamic — UUID changes on restart)
PROVIDER_ID=$(sqlite3 ~/.cc-switch/cc-switch.db \
  "SELECT id FROM providers WHERE app_type='codex';")
echo "Codex provider: $PROVIDER_ID"

# 2. Check what model CC Switch is currently using
sqlite3 ~/.cc-switch/cc-switch.db \
  "SELECT substr(settings_config, instr(settings_config, 'model ='), 50) \
   FROM providers WHERE id = '$PROVIDER_ID';"

# 3. Update the model (e.g. to deepseek-v4-flash-260425)
sqlite3 ~/.cc-switch/cc-switch.db \
  "UPDATE providers SET settings_config = \
   REPLACE(settings_config, 'model = \"ark-code-latest\"', \
   'model = \"deepseek-v4-flash-260425\"') \
   WHERE id = '$PROVIDER_ID';"

# 4. Verify the change
sqlite3 ~/.cc-switch/cc-switch.db \
  "SELECT substr(settings_config, instr(settings_config, 'model ='), 50) \
   FROM providers WHERE id = '$PROVIDER_ID';"
```

After updating, restart Codex. **Note:** CC Switch recreates the provider with a new UUID on restart, so always query by `app_type='codex'` rather than caching the UUID.

See `references/cc-switch-troubleshooting.md` for full details including schema inspection, common models that work with `/responses`, and how to recover if CC Switch reverts the change.

For Gateway SSE streaming debugging (Responess API translation, path matching, model name issues), see `references/gateway-sse-debugging.md`.

For batch image style analysis, standardization, and quality scoring (used in knowledge card projects), see `references/batch-image-style-analysis.md`.

### Post-Upgrade Recovery (v0.144+)

After `npm install -g @openai/codex@latest`, Codex auto-discovers plugins from marketplace directories. No manual reinstallation needed in v0.144+.

Quick post-upgrade checks:
```bash
codex --version
codex plugin list 2>&1 | head -5
grep -n 'chat_completions' ~/.codex/config.toml && echo "⚠️ wire_api must be 'responses'"
curl -s http://127.0.0.1:18888/health
```

Common issues:
- `wire_api = "chat_completions"` → `"responses"` (persistent pitfall across versions)
- Gateway using old code → `pkill -f llm_gateway && launchctl unload` + restart
- 404 on volcengine → check Gateway log for URL with extra `/v1/` prefix

### Desktop App

Codex has a native macOS desktop app. Run `codex app` to install and launch it:

```bash
codex app
```

On first run this:
1. Downloads a ~505MB DMG from `https://persistent.oaistatic.com/codex-app-prod/Codex.dmg`
2. Mounts the installer
3. Installs to `/Applications/Codex.app`
4. Launches the app

Subsequent runs open the existing app directly. The desktop app runs as a full
Electron-style process tree (main, renderer, GPU, network service).

After installation, the app can also be launched from Launchpad or
`/Applications/Codex.app`.

**Note:** `codex app` is a foreground process — use `background=true` in terminal
calls, or just tell the user to open it from /Applications.

### CLI ↔ Desktop App Shared State (verified 2026-08-13)

CLI 和桌面端 Codex **共用同一套 `~/.codex/` 状态存储**，不是各存各的。实测（华哥机器）确认：

| 共享存储 | 内容 |
|---------|------|
| `~/.codex/session_index.jsonl` | 会话索引（列表） |
| `~/.codex/sessions/YYYY/MM/` | 会话存档（按月） |
| `~/.codex/archived_sessions/rollout-*.jsonl` | 归档会话 |
| `~/.codex/state_5.sqlite` / `goals_1.sqlite` / `memories_1.sqlite` | 状态 / 目标 / **记忆** |
| `~/.codex/logs_2.sqlite` | 日志 |

- **CLI 跑完的任务**会落盘到 `session_index.jsonl` + `sessions/` 归档；桌面端（同一引擎、读同一 `~/.codex`）刷新/重启后能在会话列表和历史里看到。反向同理——桌面端产生的会话 CLI 也能读到。
- **`memories_1.sqlite` 记忆库共享** — CLI 任务里形成的"记忆"，桌面端后续会带上。
- **不是实时同步，是"落盘后可见"** — CLI 运行时桌面端不会实时看到中间过程；要等会话写完、桌面端刷新/重启后才出现。
- **桌面端自己的 `~/Library/Application Support/Codex/` 是独立 Electron/Chromium UI 缓存**（Cookie、Crashpad、SingletonSocket 等），不含对话内容；迁移 `~/.codex` 时不用管它。

### Doubao (豆包) Model Configuration — Direct via LLM Gateway

Codex can be configured to use Doubao (豆包) models from Volcengine Agent Plan directly, without CC Switch. This provides access to code-specialized models, vision capabilities, and faster reasoning models.

**`~/.codex/config.toml` (complete Doubao setup):**
```toml
# ========================================
#   Codex 豆包大模型配置
# 通过本地 LLM Gateway 访问火山引擎豆包
# ========================================

# Default model - Doubao code-specialized model (RECOMMENDED)
model = "doubao-seed-2-0-code-preview"

# Provider setup
[provider]
name = "custom"
base_url = "http://127.0.0.1:18888/openai/v1"  # API root — Codex adds /responses and /models
wire_api = "responses"

# Available models (via Gateway → Volcengine Agent Plan)
models = [
  # ===== 豆包系列 (推荐) =====
  "doubao-seed-2-0-code-preview",    # ✅ 代码专用（默认，最佳选择）
  "doubao-seed-2-0-pro",              # ✅ 通用Pro（思考强，推理好）
  "doubao-seed-2-0-lite",             # 🚀 轻量版（速度快）
  
  # ===== DeepSeek 系列 =====
  "deepseek-v4-pro",                  # 🧠 通用最强
  "deepseek-v4-flash",                # ⚡ 快速版
  
  # ===== GLM 系列 =====
  "glm-5.2-pro",                      # 📚 智谱清言
]

# Sandbox permissions
[sandbox]
permissions = [
  "disk-full-read-access",
  "network-full-access",
  "shell-full-access",
]

# Shell environment
[shell_environment_policy]
inherit = "all"

# Feature toggles
[features]
web_search = true
mcp = true
plugins = true
vision = true  # Enable vision for Doubao models

# ========================================
# Vision model config (for image analysis)
# ========================================
[vision]
model = "doubao-seed-2-0-pro"  # Vision-capable model
max_images = 10

# ========================================
# Model aliases (quick switching)
# ========================================
[model_aliases]
code = "doubao-seed-2-0-code-preview"  # Default, code-focused
pro = "doubao-seed-2-0-pro"            # Strong reasoning
lite = "doubao-seed-2-0-lite"          # Fast responses
ds = "deepseek-v4-pro"                  # DeepSeek general-purpose
flash = "deepseek-v4-flash"            # DeepSeek fast
glm = "glm-5.2-pro"                     # GLM long-context
```

**Quick switch examples:**
```bash
# Default (code model)
codex

# Pro reasoning mode
codex -m pro

# With images (vision analysis)
codex -i /path/to/screenshot.png

# Using aliases
codex -m code    # Code model
codex -m lite    # Fast mode
```

**Model capabilities:**
- `doubao-seed-2-0-code-preview` — 262K context, code-focused, text-only
- `doubao-seed-2-0-pro` — 1M context, strong reasoning, vision support
- `doubao-seed-2-0-lite` — 1M context, fast responses, cost-effective
- `deepseek-v4-pro/flash` — 1M context, pure text (no vision)
- `glm-5.2-pro` — 1M context, vision support, long document processing

### Codex Config Path Pitfalls — 2026-07-13 Findings

**Critical discoveries when configuring Doubao models:**

1. **Codex IGNORES $HOME variable** — It always reads config from `/Users/hua/.codex/config.toml` (hardcoded user home). When running under a different Hermes profile (e.g. `zhenglishi`), the profile's home `.codex/` is **completely ignored**. Update the real user home config only.

2. **`[features].plugins` must be boolean, NOT an array** — This is the #1 silent config parse failure:
   ```toml
   # ❌ WRONG — causes: "invalid type: string browser, expected a boolean"
   [plugins]
   enabled = ["browser", "github", "computer-use"]

   # ✅ CORRECT — plugins enabled is a single boolean flag
   [features]
   plugins = true
   ```
   Plugin auto-discovery works from marketplace cache directories — the `[plugins]` table with array is deprecated.

3. **Config cached in SQLite** — After config changes, clear state caches to ensure changes take effect:
   ```bash
   rm -f ~/.codex/state_5.sqlite*
   rm -f ~/.codex/goals_1.sqlite*
   rm -f ~/.codex/memories_1.sqlite*
   rm -f ~/.codex/logs_2.sqlite*
   ```
   Otherwise Codex may continue using cached provider settings.

4. **`base_url` must be the API root** — Codex automatically appends `/responses` and `/models` to it. The `/models` endpoint is called for reachability health check. So:
   ```toml
   # ❌ WRONG: base_url includes /responses — Codex will call /responses/responses
   base_url = "http://127.0.0.1:18888/openai/responses"

   # ✅ CORRECT: API root with /v1 suffix — Codex calls /v1/models and /v1/responses
   base_url = "http://127.0.0.1:18888/openai/v1"
   ```
   The LLM Gateway must handle both `/openai/v1/models` (for health check) and `/openai/v1/responses` (for actual calls).

5. **How to verify provider is actually used:**
   - Run `codex doctor` and check `model provider` / `openai API base URL` lines
   - If it still shows `https://api.openai.com/v1`, your provider config is being ignored
   - Check the LLM Gateway log — if no requests come in, Codex isn't using your base_url
   - Verify with `curl http://127.0.0.1:18888/openai/v1/models` directly first

### Desktop Chinese Locale (华哥's machine)

For a full Chinese interface, add to `~/.codex/config.toml`:

```toml
[desktop]
dock-icon-preference = "app-default"
localeOverride = "zh-CN"         # Chinese menus, settings, labels
followUpQueueMode = "queue"

[agent]
language = "zh-CN"
instructions = "用中文回复，代码注释用英文"
```

The `localeOverride = "zh-CN"` switches Desktop app UI to Chinese. The `[agent]` block ensures Codex's internal agent responds in Chinese. Combined with `~/.codex/AGENTS.md` ("中文为主"), this gives a fully Chinese experience — English CLI commands, Chinese agent responses and UI.

## 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):
```
terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)
```

## Project Optimization Workflow (调研 → 任务 → 执行 → 验证)

"用 codex 优化项目"类任务的标准 4 步循环，每步验证通过后再走下一步：

1. **调研现状（自己做，不交给 codex）**：读关键源码、查运行端口（`lsof -nP -iTCP:PORT -sTCP:LISTEN`）、看 docker 状态、grep 假数据标记（`mock\|假数据\|占位\|placeholder`）。定位**具体**问题（例：OpenClaw Bridge `/cmd` 只入队不执行）。先搞清"哪里是假的/不可用"再派活。

2. **任务描述写文件，避免 shell 转义**：中文 + 引号/冒号/反引号直接塞 `codex exec "长串"` 必踩转义坑。用 write_file 写 `/tmp/codex_task.txt`，再 `codex exec --sandbox workspace-write "$(cat /tmp/codex_task.txt)"`。任务描述自包含（背景现状 + 具体改动点 + 明确要求 + 验证命令 + 报告格式），一次只给一个聚焦小任务，别一次派大活。

3. **长任务 background + notify**：codex exec 写代码约 1-3 分钟，用 `background=true, notify_on_complete=true`，再 `process(action="wait", timeout=240)` 阻塞收结果。

4. **验证 codex 产出（self-report 不可信）**：codex 报告"完成"≠真实完成。必须实测：读改动文件确认逻辑落地、`python3 -c "import ast; ast.parse(...)"` 语法、实际启动服务 + curl 健康检查。分步验证通过再派下一个任务。

Pitfall：codex 改正式项目时，工作区常有历史未提交改动，codex 会叠加其上。验证前先 `git status --short` 确认本次改动范围，别把历史遗留当成本次产出误判。

## Background Mode (Long Tasks)

```
# Start in background with PTY
terminal(command="codex exec --full-auto 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
# Returns session_id

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Send input if Codex asks a question
process(action="submit", session_id="<id>", data="yes")

# Kill if needed
process(action="kill", session_id="<id>")
```

## Multi-Step Optimization Tasks (多步优化任务)

When delegating a multi-step code-optimization task to Codex (e.g. "optimize this system, replace fake components, wire up a fallback"):

1. **调研现状 first** — read the architecture docs and the actual code yourself, identify what's fake/unusable/placeholder. Don't hand Codex a vague "improve this" — give it a precise list of concrete problems (e.g. "openclaw_bridge.py `/cmd` only appends to a list and returns 'queued', never executes").
2. **写任务描述到文件** — write the self-contained prompt via `write_file` to `/tmp/codex_task.txt`, then run `codex exec "$(cat /tmp/codex_task.txt)"`. This avoids shell-quoting hell with Chinese + special chars + newlines. Verified pattern (2026-08-16): 2 sequential optimization tasks completed cleanly this way.
3. **任务描述四段式** — (a) 背景 (b) 现状问题清单 (c) 具体任务+文件路径 (d) 要求/验证命令. Self-contained so Codex completes without follow-up questions.
4. **background=true + notify_on_complete=true** — a real code task takes 1-3 min; don't block. Poll with `process(action="wait", timeout=240)`.
5. **验证产出，别信 self-report** — Codex's final summary is a SELF-REPORT. After it finishes, independently verify: `stat` the files it claims to have created, `read_file` the key changed function to confirm the logic actually landed, actually start the service and `curl` its health/error endpoint. Same rule as subagent delegation.
6. **冒烟测试 first** — before a big task, run `codex exec --sandbox read-only --skip-git-repo-check "用一句话中文回答:..."` and check output shows `tokens used` > 0 — proves Codex reaches the LLM before you burn a full task on it.
7. **改动范围隔离** — tell Codex explicitly "只新增 X 文件 + 重命名 Y 为 .bak，不碰其他文件"; afterwards `git status --short` to confirm the diff is only what you asked for (working tree may already have unrelated uncommitted changes — don't attribute them to Codex).

## Key Flags

| Flag | Effect |
|------|--------|
| `exec "prompt"` | One-shot execution, exits when done |
| `--sandbox workspace-write` | ✅ Current — sandboxed, auto-approves workspace writes |
| `--sandbox read-only` | Read-only sandbox (safe review) |
| `--sandbox danger-full-access` | No sandbox, full access (dangerous) |
| `--search` | Enable live web search (native Responses `web_search` tool) |
| `-m <model>` | Override model for this session |
| `-C <dir>` | Set working directory |
| `-p <profile>` | Layer a profile config on top |
| `--full-auto` | ⚠️ Deprecated, use `--sandbox workspace-write` instead |
| `--yolo` | No sandbox, no approvals (fastest, most dangerous) |

## Workspace Preparation (Batch Repos)

When the user asks Codex to explore, analyze, or work on **multiple repos at once**, prepare a workspace first. See `references/workspace-preparation.md` for the full pattern:

- Parallel background clones with `--depth 1`
- Handling 404 repos (wrong org/repo name)
- Verification and common pitfalls

```bash
# Quick reference: batch clone into a workspace
mkdir -p ~/codex-workspace
# Then clone each repo in parallel with background=true
```

## PR Reviews

Clone to a temp directory for safe review:

```
terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && codex review --base origin/main", pty=true)
```

## Parallel Issue Fixing with Worktrees

```
# Create worktrees
terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")

# Launch Codex in each
terminal(command="codex --yolo exec 'Fix issue #78: <description>. Commit when done.'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex --yolo exec 'Fix issue #99: <description>. Commit when done.'", workdir="/tmp/issue-99", background=true, pty=true)

# Monitor
process(action="list")

# After completion, push and create PRs
terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")

# Cleanup
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
```

## Batch PR Reviews

```
# Fetch all PR refs
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")

# Review multiple PRs in parallel
terminal(command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'", workdir="~/project", background=true, pty=true)
terminal(command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'", workdir="~/project", background=true, pty=true)

# Post results
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")
```

## Pitfalls

1. **Daily maintenance: plugin list is empty when not logged in** — `codex plugin list` returns "No marketplace plugins found" without OpenAI login. This is normal behavior, NOT an error. The 16 plugins are cached and work fine, they just won't show up in the list until marketplace auth works.
2. **npm path mismatch warning in codex doctor** — Running codex is at `/Users/hua/.local/lib/node_modules/@openai/codex` but npm global root is `/usr/local/lib/node_modules/@openai/codex`. This causes "would update a different install" warning. Use the local prefix install method to upgrade safely.
3. **GitHub sync has TWO scripts** — `~/6-产品研发/22-出图智能体训练/sync_codex_repo.sh` is a local-only legacy script (no remote configured, saves to `~/codex-workspace/`). For actual GitHub push, use `~/.hermes/scripts/codex_github_sync.sh` which targets `/tmp/yuxin-skills-codex-sync/` with the pre-configured `git@github.com:openclaw-cn-dev/yuxin-skills.git` remote. The cron task should run the hourly sync script after version/plugin checks, not the legacy local script.
4. **Config path is hardcoded to user home** — Codex ignores `$HOME` and always reads from `/Users/hua/.codex/config.toml`. Profile-specific `.codex/` directories (e.g. under `~/.hermes/profiles/`) are completely ignored. **Note (2026-08-13): `~/.codex` is now a symlink → `/Users/hua/系统文件夹/Codex/`**

…(truncated)
