Can I add OpenAI Codex to my existing OpenClaw installation?

Yes! You can add OpenAI Codex to an existing OpenClaw installation that already uses Anthropic Claude. Run 'openclaw onboard --auth-choice openai-codex', choose to keep your existing configuration, and complete the OAuth flow. Both models will be available for use.

Do I need a ChatGPT subscription to use Codex in OpenClaw?

Yes, you need an active ChatGPT Plus or Pro subscription. OpenAI Codex in OpenClaw uses your ChatGPT subscription credentials via OAuth authentication.

How do I switch between Anthropic and OpenAI models in OpenClaw?

You can switch models per command using the --model flag: 'openclaw run --model openai-codex/gpt-5.2-codex "your task"'. If connected via WhatsApp, you can ask your agent directly to switch models in-session without using command flags.

What do I do if OAuth fails on a headless VPS?

For headless VPS setups: copy the OAuth URL from your SSH terminal, open it in your local browser, log in with ChatGPT credentials, then copy the callback URL from the browser (even if it shows a localhost error) and paste it back into the SSH prompt. OpenClaw will extract and store the token automatically.

Will adding Codex break my existing Anthropic configuration?

No! When you run onboarding with --auth-choice openai-codex and choose 'keep existing configuration', OpenClaw adds Codex alongside your existing Anthropic setup. Your default model stays unchanged unless you explicitly set Codex as the new default.

Add OpenAI Codex (ChatGPT Subscription) to OpenClaw on a VPS

Running OpenClaw with Anthropic Claude on your VPS but want to try OpenAI's Codex model without breaking your existing setup? You're in the right place.

This guide shows you how to add OpenAI Codex to an existing OpenClaw installation on a Linux VPS. You'll use your ChatGPT subscription credentials, complete headless OAuth authentication, and switch between models on demand.

      What You'll Learn
      Add Codex to OpenClaw without breaking your Anthropic config
Complete OAuth authentication on a headless VPS
Switch between Claude and Codex models per task
Set Codex as your default model (optional)

    

Prerequisites

Existing OpenClaw installation on a Linux VPS (already using Anthropic)
Active ChatGPT Plus or Pro subscription
SSH access to your VPS
Local browser for OAuth authentication

⚠️ Important

This guide assumes you already have OpenClaw configured with Anthropic Claude. We'll add Codex alongside it, not replace it. Your existing configuration will remain intact.

Step 1: Run the Onboarding Wizard

OpenClaw's onboarding wizard can add new authentication providers without overwriting your existing config. Start by running:

openclaw onboard --auth-choice openai-codex

The wizard will prompt you with several options. Here's what to choose:

Quickstart or Advanced? → Choose Quickstart
New config or keep existing? → Choose keep existing configuration
Auth method: → Select OpenAI Codex (ChatGPT subscription)

✅ Key Point

Selecting "keep existing configuration" preserves your Anthropic setup. OpenClaw will add Codex as an additional model, not a replacement.

Step 2: Complete Headless OAuth Authentication

Because you're working on a headless VPS without a desktop browser, OpenClaw uses a callback URL flow for OAuth. Here's how it works:

The OAuth Flow

The wizard prints an OAuth URL in your SSH terminal
Copy this URL and paste it into your local browser (on your PC/Mac/phone)
Log in with your ChatGPT/OpenAI credentials
After successful login, you'll be redirected to a callback URL
Copy the entire callback URL from your browser's address bar
Paste it back into the SSH terminal when prompted

💡 Common Issue

The callback URL may show a localhost address that displays an error page. That's normal! You don't need the page to load—just copy the full URL including all parameters and paste it into your SSH session.

OpenClaw will extract the authentication token from the callback URL and store it automatically. No manual token copying required.

Step 3: Verify Codex is Available

After OAuth completes, verify that Codex was added successfully:

openclaw models list

You should see output similar to this:

openai-codex/gpt-5.2-codex   ...   configured
openai/gpt-5.2-codex         ...   configured
anthropic/claude-sonnet-4-5-20250929   ...   configured

✅ Success!

If you see Codex models listed as "configured", you're ready to use them. Both your Anthropic and OpenAI models are now available.

Step 4: Switch to Codex for Specific Tasks

You can now use Codex for specific commands without changing your default model. Use the --model flag:

openclaw run --model openai-codex/gpt-5.2-codex "your task here"

Example Use Cases

# Generate code with Codex
openclaw run --model openai-codex/gpt-5.2-codex "Write a Python script to parse CSV files"

# Debug with Codex
openclaw run --model openai-codex/gpt-5.2-codex "Explain this error: TypeError: 'NoneType' object is not subscriptable"

💬 WhatsApp Integration

If your OpenClaw agent is connected via WhatsApp (like in the screenshot below), you can simply ask it to switch models: "Switch to Codex" or "Use OpenAI Codex for this task". No command flags needed!

OpenClaw Codex model switching in WhatsApp

Step 5: Set Codex as Default (Optional)

If you want Codex to be your default model for all tasks, edit your OpenClaw config file:

nano ~/.openclaw/openclaw.json

Find the agents.defaults.model.primary field and change it to:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.2-codex"
      }
    }
  }
}

Save the file and restart OpenClaw for the change to take effect.

⚠️ Note

You can revert to Anthropic as the default anytime by changing this value back to your Claude model ID (e.g., anthropic/claude-sonnet-4-5-20250929).

Troubleshooting

Codex Not Listed After Onboarding

If openclaw models list doesn't show Codex models, try re-running the onboarding:

openclaw onboard --auth-choice openai-codex

OAuth Authentication Failed

If the OAuth callback fails:

Make sure you're logged into ChatGPT in the browser you're using
Copy the entire callback URL, including all ? and & parameters
Don't worry if the localhost page shows an error—the URL is what matters

Check Authentication Status

Verify your Codex authentication is valid:

openclaw models status

This shows the status of all configured providers. Look for OpenAI/Codex entries.

Key Takeaways

You can add Codex to OpenClaw without breaking your existing Anthropic setup
No skills installation required—just OAuth authentication
Switch between models using --model flag or in-session commands (WhatsApp)
WhatsApp integration works unchanged with multiple models
Headless OAuth uses a browser callback URL flow—no desktop GUI needed

Want to Master OpenClaw & AI Agents?

Join Vibe Coding Academy to build real AI-powered applications, automate your workflow with agents, and learn cutting-edge development techniques.

Join the Academy