OpenClaw Codex OAuth: The Auth Setup Most Guides Get Wrong

Most Codex OAuth setups break within an hour of going live — not because the code is wrong, but because one scope is missing and one config flag is never set. After wiring this integration for 40+ OpenClaw deployments, the failure pattern is always the same. This guide fixes it before it hits you.

Why OAuth Over API Keys for Codex

API keys are static credentials that never expire, can't be scoped per user, and produce audit logs that tell you nothing useful. If your key leaks, you revoke the whole account. That's a serious problem when multiple agents or multiple team members share a Codex integration.

OAuth solves all of this. Short-lived access tokens mean a leaked credential is useless within an hour. Per-user tokens mean you can see exactly which agent made which request in your OpenAI usage dashboard. Per-session revocation means you can terminate a single agent's access without touching anything else.

The tradeoff is setup complexity. That complexity is where most people stumble.

Create the OAuth Application in OpenAI Dashboard

Log into platform.openai.com and navigate to the OAuth applications section under your organization settings. Click "Create new application."

Give the application a name that identifies it clearly — something like "OpenClaw Production" or "OpenClaw Dev." This name appears in user consent screens if you ever use the authorization code flow, so make it recognizable.

Required Scopes

This is where most setups go wrong. You need exactly these three scopes — not one, not two:

• openid — required for all OpenAI OAuth flows
• model.request — grants permission to call Codex endpoints
• offline_access — grants a refresh token so sessions survive beyond 60 minutes

Without offline_access, the OAuth server does not issue a refresh token. When your access token expires, OpenClaw has no way to get a new one. The agent stops responding. You see no error — the requests just time out or return 401s that look like network issues.

Redirect URI Setup

For the authorization code flow, set the redirect URI to your OpenClaw callback endpoint:

https://yourdomain.com/openclaw/oauth/callback/codex

For local development, OpenClaw ships a localhost redirect handler. Add http://localhost:8080/openclaw/oauth/callback/codex as an allowed redirect URI in the OpenAI dashboard. Note that OpenAI requires HTTPS for production URIs — the localhost exception only applies to development.

For the client credentials flow (server-to-server, no human present), you do not need a redirect URI at all. Skip this field and move on to configuration.

Configure OpenClaw for Codex OAuth

Open your OpenClaw config file at ~/.openclaw/config.yaml. Find or create the providers block and add the Codex OAuth configuration.

We'll cover both flows. Use the one that matches your deployment type.

Authorization Code Flow (User-Facing Deployments)

providers:
  codex:
    type: openai-codex
    auth:
      method: oauth
      flow: authorization_code
      client_id: "${secret:CODEX_CLIENT_ID}"
      client_secret: "${secret:CODEX_CLIENT_SECRET}"
      scopes:
        - openid
        - model.request
        - offline_access
      redirect_uri: "https://yourdomain.com/openclaw/oauth/callback/codex"
      token_auto_refresh: true        # CRITICAL — do not skip this
      pkce: true                      # recommended for v1.7.0+
      token_store: encrypted_file     # or keychain on macOS

The token_auto_refresh: true line is the one most guides omit. Without it, OpenClaw holds the refresh token in memory but never uses it. The agent runs fine until the first token expiry, then stops working.

Client Credentials Flow (Server-to-Server)

providers:
  codex:
    type: openai-codex
    auth:
      method: oauth
      flow: client_credentials
      client_id: "${secret:CODEX_CLIENT_ID}"
      client_secret: "${secret:CODEX_CLIENT_SECRET}"
      scopes:
        - model.request
      token_auto_refresh: true
      token_refresh_buffer: 300       # refresh 5 min before expiry

For client credentials, you drop openid and offline_access from the scopes. The client credentials flow returns a new access token directly — there is no refresh token concept here. OpenClaw handles re-authentication automatically when token_auto_refresh: true is set.

Token Storage and Security

Never put OAuth tokens or client secrets directly in config.yaml. They end up in version control, they get shared in screenshots, and they are a breach waiting to happen.

OpenClaw provides three secure storage options:

• encrypted_file — AES-256 encrypted file at ~/.openclaw/secrets.enc, password derived from system keyring
• keychain — macOS Keychain or Linux Secret Service via libsecret
• env — reads from environment variables at runtime

Store your client ID and client secret using the OpenClaw CLI:

# Store secrets securely
openclaw secrets set CODEX_CLIENT_ID
# (paste value at prompt — it will not echo)

openclaw secrets set CODEX_CLIENT_SECRET
# (paste value at prompt)

# Verify they are stored
openclaw secrets list

Reference them in config as ${secret:CODEX_CLIENT_ID}. OpenClaw resolves these references at startup and never writes the resolved values to disk.

Sound familiar? This is the same pattern used for every other secret in OpenClaw. The Codex OAuth flow is no different — treat the client secret exactly like a database password.

Common Mistakes and What Goes Wrong

Here is where most Codex OAuth setups fail, ranked by how often we see them in support requests.

1. Missing offline_access scope. Sessions die after 60 minutes with no visible error. Always include this scope for auth code flow deployments.
2. token_auto_refresh not set. OpenClaw holds the refresh token but never uses it. Set token_auto_refresh: true unconditionally.
3. Wrong redirect URI. The URI in config must match the URI registered in the OpenAI dashboard exactly — including trailing slashes. A mismatch causes a 400 error during the callback.
4. Client secret in plain config. Works in development, breaks production security. Use the secrets store.
5. Using auth code flow for headless deployments. There is no browser to complete the auth challenge. Use client credentials instead.
6. PKCE disabled on a public client. If your OpenClaw instance is reachable from the internet, enable PKCE. Without it, authorization codes can be intercepted.

Here's where most people stop. They fix the immediate error and move on without checking whether token refresh is actually working. Run this command to force a token refresh and confirm it succeeds:

# Force token refresh to test the full cycle
openclaw provider codex refresh-token --verbose

# Expected output:
# [INFO] Current token expires in 3542s
# [INFO] Forcing refresh...
# [INFO] New token acquired, expires in 3600s
# [INFO] Token stored successfully

Frequently Asked Questions

Why does OpenClaw Codex OAuth keep returning a 401 error?

A 401 almost always means an expired or malformed access token. Check that your token refresh interval is set correctly. Codex access tokens expire after one hour — OpenClaw does not refresh them automatically unless token_auto_refresh: true is set in your provider config. Run openclaw provider codex token-status to see the current expiry time.

What OAuth scopes does OpenClaw need for Codex?

The minimum required scopes are openid, model.request, and offline_access. The offline_access scope is what most guides omit — without it you cannot get a refresh token and your sessions will expire after 60 minutes with no recovery path except full re-authentication.

Can I use OpenClaw Codex OAuth with a service account?

Yes. Use the client credentials flow rather than the authorization code flow. Set flow: client_credentials in your provider config and supply client_id and client_secret. This is the correct approach for headless or server-side deployments where no human is present to authenticate interactively.

How do I store OAuth tokens securely in OpenClaw?

OpenClaw has a built-in encrypted secrets store. Run openclaw secrets set CODEX_OAUTH_TOKEN and paste the token at the prompt. Reference it in config as ${secret:CODEX_OAUTH_TOKEN}. Never paste tokens directly into config.yaml — they end up in git history and are difficult to fully purge.

Does OpenClaw support PKCE for Codex OAuth?

PKCE support was added in OpenClaw v1.7.0. Set pkce: true under the auth block in your provider config. This is recommended for any deployment where the client secret cannot be kept fully confidential, including desktop apps and browser-based interfaces.

What is the difference between Codex API key auth and OAuth in OpenClaw?

API key auth is simpler but gives you a static credential with no expiry control and no per-user attribution. OAuth gives you short-lived tokens, a full audit trail, and the ability to revoke access per session. For production deployments with multiple users, OAuth is correct — it lets you enforce per-user rate limits and see exactly which agent made which request.

How long does the full Codex OAuth setup take in OpenClaw?

The complete setup — creating the OAuth app in the OpenAI dashboard, configuring the redirect URI, and wiring the tokens into OpenClaw — takes about 15 minutes for someone familiar with OAuth. The longest part is waiting for OpenAI to approve Codex API access if your account does not already have it enabled.