easyNode

Product

Enabling OpenAI OAuth

Enabling OpenAI OAuth

This guide explains how to authenticate OpenClaw with OpenAI Codex using OAuth, then switch your agent to an OpenAI-backed model.

What this does

OpenClaw can use OpenAI Codex via OAuth login (instead of manually pasting API keys). After auth succeeds, you can select an openai-codex/... model for the current session or set it as default.

Prerequisites

  • OpenClaw is installed and running
  • You can access the terminal on the host
  • You can open a browser on your local machine for the OAuth login flow

Note: OpenClaw is personal-by-default. If deploying in shared/multi-user settings, apply proper lock-down/auth controls first.

1) Start the OAuth onboarding flow

openclaw onboard --auth-choice openai-codex

This starts the OpenAI OAuth flow and stores credentials in your OpenClaw auth profile.

If prompted with a safety confirmation like:

“I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?”

Choose Yes if this is your intended single-user setup (or after completing your security hardening).

⚠️ Important: Preserving existing configuration

If you already have OpenClaw configured (workspace, model, gateway mode), the onboarding wizard will detect your existing config and prompt:

Existing config detected

Always select “Use existing values” to preserve your current configuration. This prevents the wizard from overwriting your workspace path, model settings, or gateway mode.

  • ✅ Use existing values — Keeps your current setup, only adds OpenAI OAuth
  • ❌ Update values — Will prompt you to reconfigure everything
  • ❌ Reset — Wipes your config (not recommended)

2) Complete OAuth in your local browser

During onboarding, OpenClaw will print an auth URL. Open that URL in your local browser and sign in with OpenAI.

After approving access, OpenAI may redirect (or offer a link) to a callback URL like:

http://localhost/...

On remote/VPS setups this often looks broken, with a message such as:

“This site can’t be reached” “localhost refused to connect.”

This is expected in many setups - because openclaw assumes you are running the setup process on the same box you are authenticating at OpenAI from - with easyClaw/easyNode this is not the case:

What to do next

  1. Copy the entire http://localhost/... URL from the browser address bar.
  2. Return to your OpenClaw onboarding/configuration wizard in terminal.
  3. Paste that full URL when prompted.

This completes the OAuth handoff even if the browser page itself fails to load.

3) Verify provider/model availability

openclaw models status

You should see OpenAI Codex provider/model entries available.

4) Switch model

For current chat/session

Use chat command:

/model openai-codex/gpt-5.3-codex

For default across new sessions

openclaw config set defaultModel openai-codex/gpt-5.3-codex

Common issue: “No provider plugins found. Install one via openclaw plugins install.”

If you see this while trying auth/login, run the onboarding command directly:

openclaw onboard --auth-choice openai-codex

In current builds, OpenAI Codex OAuth is handled through onboarding flow (not necessarily via separately installed provider plugin).

Troubleshooting checklist

  1. Re-run status:
openclaw models status
  1. Confirm active model in-session with /status (or equivalent status card).
  2. If model did not change, run:
/model openai-codex/gpt-5.3-codex
  1. If onboarding/auth fails, retry onboarding:
openclaw onboard --auth-choice openai-codex
  1. If browser redirect fails with localhost error, copy the full http://localhost/... callback URL and paste it back into the wizard prompt.

Security notes

  • Personal appliance setups are simplest and safest by default.
  • If exposed beyond single-user local control:
  • enable Gateway auth
  • restrict network exposure
  • enforce authorized sender allowlists
  • use firewall hardening (UFW/fail2ban/etc.)