Sign in to OpenQiao with OAuth PKCE ​

OpenQiao supports connecting local agents through OAuth 2.0 Authorization Code + PKCE. This flow does not require you to create, copy, or store a OpenQiao API key. The agent opens a browser for authorization, uses a short-lived access token for model requests, and refreshes the token before it expires.

The following agents are currently supported:

Authorization flow ​

These integrations follow the same core flow:

1. The agent generates a one-time PKCE code_verifier and its S256 code_challenge.
2. A browser opens the OpenQiao authorization page, where you confirm the account and requested access.
3. OpenQiao returns a one-time authorization code to a temporary callback port on 127.0.0.1.
4. The plugin exchanges the authorization code and code_verifier for an access token and refresh token.
5. The agent uses the access token for OpenQiao requests and refreshes it before expiration.

The official packages request only these scopes by default:

• inference:invoke: invoke models.
• offline_access: refresh the sign-in session after the access token expires.

OpenClaw ​

Install the plugin and start sign-in:

openclaw plugins install @openqiao/openclaw-plugin
openclaw models auth login --provider openqiao

Select OpenQiao OAuth, finish authorization in the browser, and then choose a openqiao/... model in OpenClaw.

OpenClaw stores tokens in its own authentication profile store and persists rotated refresh tokens automatically. Models are discovered dynamically, with the latest valid catalog cached at ~/.cache/openclaw/openqiao/models.json.

Codex CLI and Codex App ​

Install the authentication tool globally:

npm install -g @openqiao/codex-oauth

Configure Codex and sign in:

openqiao-codex-auth install
openqiao-codex-auth login

Restart Codex CLI or Codex App afterward. install configures OpenQiao as a Responses provider and downloads the current Responses-compatible model catalog without changing your existing model name. An existing ~/.codex/config.toml is backed up first.

Inspect or clear the sign-in state with:

openqiao-codex-auth status
openqiao-codex-auth logout

To remove the integration completely, restore the Codex configuration before uninstalling the npm package:

openqiao-codex-auth uninstall
npm uninstall -g @openqiao/codex-oauth

DeepSeek Harness ​

For complete installation, proxy, and model configuration details, see DeepSeek Harness Integration.

Install the OpenQiao bundle into the DSH Web profile, then start DSH:

dsh plugin --profile web add @openqiao/dsh-plugins
dsh web

Run this command in DSH Web:

/openqiao login

After browser authorization displays OpenQiao connected, return to DSH and select OpenQiao · DeepSeek V4 Pro or OpenQiao · DeepSeek V4 Flash from the model selector.

Manage the sign-in state with:

/openqiao status
/openqiao logout

OpenCode ​

Add the OAuth package to your OpenCode configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@openqiao/opencode-oauth"]
}

Then run:

opencode auth login -p openqiao -m "OpenQiao OAuth (PKCE)"

Alternatively, run /connect in OpenCode, select OpenQiao, and choose OpenQiao OAuth (PKCE). After authorization, run /models and select a OpenQiao model.

OpenCode keeps access and refresh tokens in its own credential store. The catalog maps each model to Anthropic Messages, OpenAI Responses, or Chat Completions and is cached at ~/.cache/opencode/openqiao/models.json.

Pi ​

Install the extension with Pi:

pi install npm:@openqiao/pi-openqiao-oauth

After starting Pi, sign in with:

/login openqiao

When browser authorization finishes, return to Pi, run /model, and select a OpenQiao model. Pi manages access and refresh tokens through its provider credential store and caches the model catalog at ~/.pi/agent/models-store.json.

Hermes Agent ​

For complete installation, default provider configuration, remote authorization, and troubleshooting, see Hermes Agent Integration. Source code and alternative installation methods are available at OpenQiao/hermes-plugin.

Install and enable the plugin:

hermes plugins install OpenQiao/hermes-plugin --enable
hermes gateway restart

If no Gateway is running, restart Hermes instead. Restart Gateways managed by PM2 or another process manager through that manager.

Sign in and check status:

hermes auth add openqiao
hermes auth status openqiao

On the OpenQiao authorization page, select your account and billing option, then approve access. OAuth avoids manually creating an API Key, but model requests are still billed to the selected account and billing option.

After authorization, run hermes model and select the plugin's OpenQiao provider and a model, or specify them explicitly:

hermes --provider openqiao -m google/gemini-2.5-flash-lite

Send a test message and confirm that the model responds. openqiao is the provider name; use the full vendor/model slug without adding a openqiao/ prefix. When migrating from an API Key custom endpoint, switch the provider from custom to openqiao rather than only replacing credentials.

Hermes stores access and refresh tokens in its credential pool and serializes refresh token rotation through credential locks. The plugin reads the live model catalog and filters image-only and video-only generation models. Valid unlisted slugs require Hermes support for ProviderProfile.model_listing_authoritative; API permissions and responses remain authoritative.

Manage authentication with:

hermes auth list openqiao
hermes auth refresh openqiao
hermes auth logout openqiao

Credential storage and security ​

• Production uses bundled native public client IDs. No client secret is stored in the plugin packages.
• Callback listeners bind only to temporary ports on 127.0.0.1 and validate OAuth state.
• Access tokens are refreshed before expiration. When the server rotates a refresh token, the plugin saves the replacement.
• Never copy OAuth tokens into model settings, environment variables, logs, or screenshots.
• When you stop using an agent, sign out from the agent and revoke its grant from OpenQiao Authorized Apps.

Troubleshooting ​

The browser does not open automatically ​

Copy the authorization URL printed in the terminal into a browser. For Codex, you can also set:

export OPENQIAO_OAUTH_NO_BROWSER=1
openqiao-codex-auth login

The terminal keeps waiting after browser authorization ​

The OAuth callback uses a temporary port on 127.0.0.1. Confirm that a firewall is not blocking loopback connections and that the authorization browser can reach the callback on the machine running the agent. In remote or container environments, the browser's 127.0.0.1 is not necessarily the agent host. OpenClaw supports pasting the full redirect URL back into the terminal. For Hermes, use --no-browser and forward the actual callback port for the current login; see Remote authorization.

Sign-in succeeds, but OpenQiao models are missing ​

Reopen the agent's model selector and confirm that the model catalog endpoint is reachable. OpenClaw, OpenCode, and Pi preserve the last valid catalog cache. DeepSeek Harness currently provides two bundled model entries. Codex writes its catalog during openqiao-codex-auth install; run that command again after the production catalog changes.

Hermes uses the live catalog rather than the disk catalog caches described above. For Unknown provider, run hermes plugins list to confirm installation and enablement, then restart Hermes / Gateway. If a valid unlisted slug is rejected, update Hermes and the plugin; see Hermes troubleshooting.