OpenAI Subscription (ChatGPT) – Paste Flow

Use your OpenAI subscription (ChatGPT or Codex) to power AI models in your HB OpenClaw agent instead of an API key.

Why Do I Need OpenClaw CLI on My Machine?

Your HB OpenClaw agent runs on HeroBoost's infrastructure. OpenAI OAuth requires a browser to log in and grant access. HeroBoost's servers do not have a browser.

Solution: Run OpenClaw CLI once on your local machine (laptop or PC). It opens a browser, you complete the OAuth flow, and it saves the credentials to a file. You then copy that file's contents and paste it into the HeroBoost Configure page. HeroBoost sends it securely to your agent instance. After that, you can remove the local OpenClaw install or keep it and run it alongside your HB instance—your choice. The local install is only an intermediate step to complete authentication.

Where	Role
Your local machine	OpenClaw CLI generates oauth.json (needs browser, one-time)
HeroBoost Configure page	You paste the JSON and save
HeroBoost server	Your agent runs here and uses the credentials

Is a Local Instance Mandatory?

Yes. OpenAI OAuth needs:

• A browser to log in and authorize
• A localhost callback (port 1455) to receive the authorization code
• OpenClaw CLI running locally to host that callback server

Two Instances, Same OAuth Account

This setup creates two separate OpenClaw instances that share the same OpenAI OAuth account:

Instance	Location	Purpose
Local	Your machine (~/.openclaw/)	Used to run OAuth flow and generate oauth.json; you can chat with it locally via TUI
HB	HeroBoost VPS	Your agent for users; receives oauth.json when you paste it in Configure

Both use the same OpenAI subscription. You choose what to do with the local instance:

• Remove it later – Run rm -rf ~/.openclaw when you no longer need it.
• Keep it and run both – Use the local instance for personal testing and the HB instance for your users. They are independent.

Quick Steps

1. Install OpenClaw CLI on your local machine (see below).
2. Run openclaw onboard --auth-choice openai-codex and complete the OAuth flow in your browser.
3. Copy the contents of ~/.openclaw/agents/main/agent/auth-profiles.json (or auth.json; see "Generate and Paste OAuth JSON" for paths).
4. Open your agent's Configure page in HeroBoost.
5. Select Provider = OpenAI, Auth mode = OAuth (ChatGPT subscription).
6. Paste the JSON into the OAuth JSON field and click Save.

Install OpenClaw CLI (Brief)

macOS / Linux / WSL:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard

Local install (no root):

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

Windows (PowerShell):

iwr -useb https://openclaw.ai/install.ps1 | iex

After install, open a new terminal and run:

openclaw onboard --auth-choice openai-codex

You will see several prompts (e.g. "Continue?", "Onboarding mode", "What do you want to set up?"). Choose Local gateway (this machine) – this is required for the OAuth callback.

A browser will open. Log in to OpenAI (or create an account) and authorize. When done, the credentials are saved to ~/.openclaw/agents/main/agent/auth-profiles.json (or auth.json).

If the terminal shows "Paste the authorization code (or full redirect URL):" – the callback did not auto-complete. Copy the full URL from your browser's address bar (e.g. http://localhost:1455/auth/callback?code=ac_xxx...) and paste it into the terminal, then press Enter. If the first run fails, run the command again; a second attempt often completes automatically.

Generate and Paste OAuth JSON

1. Run the command above on your local machine.
2. After OAuth completes, find the credentials file. OpenClaw may store it in one of these locations:
   • macOS/Linux: ~/.openclaw/agents/main/agent/auth-profiles.json (or auth.json)
   • Alternative: ~/.openclaw/credentials/oauth.json
   • Windows: %USERPROFILE%\.openclaw\agents\main\agent\auth-profiles.json (or credentials\oauth.json)
3. Copy the entire JSON content. The format may look like:

   {"openai-codex":{"type":"oauth","access":"...","refresh":"...","expires":...}}
   

   Paste the whole object (including the openai-codex key) – do not add extra wrapper.
4. In HeroBoost, go to Agent > Configure > Basic tab.
5. Select Provider = OpenAI, Auth mode = OAuth (ChatGPT subscription).
6. Paste the JSON into the OAuth JSON text area and click Save.

FAQ

How much disk space does the local install use?

Workspace is at ~/.openclaw/workspace. To check size:

du -sh ~/.openclaw

Typically a few dozen MB to ~100MB (CLI + workspace).

Can I remove the local instance? Or keep both?

Your choice. The local and HB instances are separate. You can:

• Remove the local instance when you no longer need it:

  rm -rf ~/.openclaw
  

  (If you installed via the install script, you may also need to remove the binary – check with which openclaw.)

• Keep both – Run the local instance for personal use and the HB instance for your users. They share the same OpenAI account but are independent.

I closed the tab with the callback URL. What now?

The authorization code is single-use and short-lived. Run the command again:

openclaw onboard --auth-choice openai-codex

Complete the OAuth flow in the browser again. If the terminal asks you to paste the URL, copy the full URL from the address bar and paste it before closing the tab.

Reference

• OpenClaw Installer – Full install options
• OpenClaw OpenAI Provider – OAuth flow details
• Hero Configuration Overview – Other settings

---

Last Updated: 2026-02-26