Codex OAuth with OpenClaw

OpenClaw can call OpenAI models through an API key or through OAuth tied to a ChatGPT/Codex subscription. OAuth is attractive when you already pay for Codex and do not want a separate metered key—but routing and recovery steps matter, especially after upgrades.

This tutorial focuses on the openai-codex provider path. For general OpenAI setup, see OpenAI provider guide. Exact flags live in official OpenAI provider docs.

• OpenClaw installed (installation) and Gateway able to reach the internet.
• A ChatGPT plan that includes Codex (check OpenAI's current plan names—they change).
• Browser on the same machine (or copy-paste friendly remote desktop) for the OAuth redirect.
• Pick one auth method per provider—OAuth or API key, not both fighting in config.

From a terminal on the Gateway host:

openclaw models auth login --provider openai-codex

Complete the browser sign-in. Tokens are stored in your agent auth profiles (see official OAuth concepts).

Alternatively, run openclaw onboard and choose OpenAI/Codex OAuth when prompted (configuration).

Your default model should use the openai-codex/ route namespace—not a stale API-key profile. After onboarding, check ~/.openclaw/openclaw.json (or use Control UI) for the active model id.

Smoke test in WebChat or a paired channel:

openclaw gateway start
openclaw doctor

Send a short message. If you get auth errors, continue to troubleshooting below.

Some releases rewrote Codex routes when users ran openclaw doctor --fix. After upgrading, if Codex stopped working:

1. Read the release notes for your version on releases.
2. Follow upstream Codex OAuth recovery.
3. Re-run openclaw models auth login --provider openai-codex if tokens expired.
4. Run openclaw security audit --deep—auth changes sometimes surface stale bind or auth modes.

Coding-agent comparison (OpenClaw assistant vs Claude Code product): OpenClaw vs Claude Code.