# Enabling OpenAI OAuth

> Authenticate with OpenAI (ChatGPT/Codex) via OAuth and switch your agent to OpenAI models.


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

------

## 1) Authenticate (recommended: device-code flow)

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

```bash
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:

```text
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](#legacy-onboarding-flow-localhost-callback) below.

------

## 2) Verify provider/model availability

```bash
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:

```text
/model openai/gpt-5.4
```

### For default across new sessions

```bash
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:

```bash
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](#3-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

```bash
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](images/openai-oauth-existing-config.jpg)

**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:

```text
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](#1-authenticate-recommended-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:

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

On older builds, run the onboarding command directly:

```bash
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:

   ```bash
   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:

   ```text
   /model openai/gpt-5.4
   ```

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

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

---
_Canonical: https://easynode.ai/docs/openai-oauth/index.md_