easyNode

Product

Enabling OpenAI OAuth

Enabling OpenAI OAuth

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

What this does

OpenClaw can use your ChatGPT Plus/Pro subscription via OAuth login (instead of manually pasting API keys). After auth succeeds, you can select an OpenAI model for the current session or set it as default.

⚠️ Provider id changed in OpenClaw 2026.6

Check your version first: openclaw --version.

OpenClaw ≤2026.4.x OpenClaw ≥2026.6.x
Provider id openai-codex openai
Model refs openai-codex/gpt-5.4 openai/gpt-5.4

On ≥2026.6, any command using openai-codex fails with “No provider plugins found” — use openai instead. The current fleet is on ≥2026.6, so the examples below use openai; if you are still on a legacy build, substitute openai-codex per this table.

Prerequisites

  • OpenClaw is installed and running
  • You can access the terminal on the host
  • You can open a browser on any device (phone, laptop — it does not need to be the host) to approve the login

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

On an easyClaw/easyNode appliance, run this as the openclaw user:

sudo -u openclaw HOME=/home/openclaw openclaw models auth login --provider openai --device-code

The CLI prints a verification URL and a short code, for example:

Open https://chatgpt.com/device and enter code: ABCD-EFGH
  1. Open that URL in a browser on any device.
  2. Sign in to OpenAI (ChatGPT) and enter the code.
  3. Approve access. The terminal completes the login automatically and stores the credentials in your OpenClaw auth profile.

That’s it — no localhost callback URL to copy/paste. This is the method to use for both first-time setup and re-authentication.

Why --device-code? OpenClaw’s default OAuth flow assumes you’re running setup on the same machine you’re browsing from, and redirects to a http://localhost/... callback. On a remote VPS that callback can’t load. The device-code flow sidesteps it entirely by letting you approve from any browser. If you’re on a build that doesn’t support --device-code, use the legacy onboarding flow below.

2) Verify provider/model availability

sudo -u openclaw HOME=/home/openclaw openclaw models status

You should see the OpenAI provider with an ok expires in ... profile and model entries available.

3) Switch model

For current chat/session

Use the chat command:

/model openai/gpt-5.4

For default across new sessions

sudo -u openclaw HOME=/home/openclaw openclaw config set defaultModel openai/gpt-5.4

Renewing an expired Codex / ChatGPT OAuth login

OAuth credentials expire periodically (and a stale refresh token is rejected with “Your refresh token has already been used to generate a new access token”). When that happens, just re-run the same device-code login — there’s no need to repeat the full onboarding flow:

sudo -u openclaw HOME=/home/openclaw openclaw models auth login --provider openai --device-code

This refreshes the stored credentials in place, preserving your existing workspace, model, and gateway configuration.

Verify afterwards with openclaw models status — the profile should show ok expires in ... — and confirm the agent actually replies. An expired model ref shows up as “Unknown model: openai-codex/…” on ≥2026.6; fix it by pointing the default model at openai/... instead (see Switch model).

Legacy onboarding flow (localhost callback)

Older builds (or setups without --device-code) authenticate through the onboarding wizard, which uses a browser localhost-callback handoff.

Start the onboarding flow

openclaw onboard --auth-choice openai

(On legacy ≤2026.4.x builds use --auth-choice openai-codex.)

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).

⚠️ 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)

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 — openclaw assumes you are running setup on the same box you are authenticating from, and with easyClaw/easyNode that 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. (The device-code flow avoids this entirely — prefer it when available.)

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

On OpenClaw ≥2026.6 this almost always means you used the retired openai-codex provider id. Re-run with the current id:

sudo -u openclaw HOME=/home/openclaw openclaw models auth login --provider openai --device-code

On older builds, run the onboarding command directly:

openclaw onboard --auth-choice openai-codex

(legacy builds handled OpenAI Codex OAuth through the onboarding flow, not necessarily via a separately installed provider plugin).

Troubleshooting checklist

  1. Re-run status:

    sudo -u openclaw HOME=/home/openclaw openclaw models status

  2. Confirm the active model in-session with /status (or equivalent status card).

  3. If the model did not change, run:

    /model openai/gpt-5.4

  4. If auth fails or the credentials expired, re-run the device-code login:

    sudo -u openclaw HOME=/home/openclaw openclaw models auth login --provider openai --device-code

  5. Only if --device-code is unavailable, fall back to onboarding and the localhost-callback handoff described above.

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.)