CLIProxyAPI Guide (2026): Turn Codex Subscription into Local API Key for Claude Code & More

Who it's for

• Developers who have a Codex subscription but mainly use Claude Code
• People who want to use a subscription account as a local API Key instead of buying API credits separately
• Users wanting to reuse Codex power in NextChat, Cherry Studio, or Cursor
• Windows users running a local proxy service

How to do it

1. Download the Windows build of CLIProxyAPI from GitHub and extract it
2. Rename config.example.yaml to config.yaml and change four values: host, api-keys, the cooldown time, and secret-key
3. Run cli-proxy-api.exe to start the service (or use a VBS script for silent background execution)
4. Open http://127.0.0.1:8317/management.html in a browser and sign in with secret-key
5. Configure a network proxy in the console, then import the Codex account with Codex OAuth
6. Open CC Switch, enter the API Key and http://127.0.0.1:8317, pick a model, and connect Claude Code

Watch out for

• An empty host listens on every network interface — if you have a public IP at home, change it to 127.0.0.1
• If you only set one key in api-keys, remember to comment out the other two default keys in the config file
• Keep the config file and keys on your own machine — never commit them to a Git repo or share them

Author: UPGPTs Team·First published: 2026-09-27·Last updated: 2026-09-27

What this article solves: You have a Codex subscription but mostly use Claude Code, so the subscription goes unused — and you would rather not buy expensive API credits on top. This guide uses the open-source tool CLIProxyAPI to run a proxy on your own machine, turn the Codex subscription account into a local OpenAI-compatible API Key, and plug it into Claude Code or other desktop clients through CC Switch. All of it tested on Windows, including how to fix the auth_unavailable cooldown error.

CLIProxyAPI works on a simple principle: it runs an OpenAI-compatible service on your machine, signs your subscription account in over OAuth, and hands out an API Key. Grok and Kimi subscriptions can be converted the same way. On the client side, Claude Code, NextChat, Cherry Studio, OpenClaw, WorkBuddy, Hermes, Pi… anything that lets you supply your own model endpoint and key will connect.

---

📚 On this page

• Before You Start: Four Requirements
• Step 1: Download and Extract CLIProxyAPI
• Step 2: Edit the Config File (Four Values)
• Step 3: Start the Service (With Silent Background Tip)
• Step 4: Open the Management Console
• Step 5: Configure a Network Proxy
• Step 6: Import the Codex Account with OAuth
• Step 7: Connect Claude Code with CC Switch
• Advanced: Connect NextChat, Cherry Studio, or Any OpenAI Client
• Verify the Connection & Troubleshooting
• Frequently Asked Questions FAQ
• Related Guides

---

Before You Start: Four Requirements

Miss one of these and nothing downstream will work:

1. A Codex subscription account. This is the account that gets turned into an API Key. If you do not have one, check the Codex Guide or ChatGPT / Codex Plan Comparison.
2. Claude Code installed locally. If you do not have it, run npm install -g @anthropic-ai/claude-code — that needs a Node.js environment first.
3. CC Switch installed locally. It is the visual tool you use at the end to put the endpoint and key into Claude Code. Download it from the official site or GitHub Releases; on Windows grab the .msi and click through. Setup and usage are covered in the CC Switch guide.
4. A network that can reach AI services. If it cannot, configure a proxy in step 5.

---

Step 1: Download and Extract CLIProxyAPI

Go to the project page, CLIProxyAPI:

Download the Windows build:

Once extracted, there is one thing you must do first: rename config.example.yaml to config.yaml. The program reads config.yaml — leave the name alone and your settings do nothing.

---

Step 2: Edit the Config File (Four Values)

Change four values in config.yaml. The first two are required; the last two are recommended.

1️⃣ host → 127.0.0.1 (required)

Set it to 127.0.0.1 so only the local machine can reach the service. The default is empty, and an empty value listens on every network interface — if you have a public IP at home, never leave it blank.

2️⃣ api-keys → a key you define (required)

Enter a string of your own choosing — this is the key you will enter in the agent later. If you want a different key per tool, add more lines.

⚠️ If you only set one key, remember to comment out the other two default keys rather than leaving them in place. It is also worth using the sk-xxxx format. Not required, but many clients check for it by convention.

3️⃣ transient-error-cooldown-seconds → 2 (added after hitting the pitfall)

Set it to 2. This is the change I made after hitting the pitfall — worth unpacking:

Why a default of 0 goes wrong. The config file's comments spell it out: 0 keeps the old rule, where a single 408 / 500 / 502 / 503 from upstream freezes that account for 60 seconds.

The trouble is that network blips are far too common. One blip puts the account into cooldown, and for those 60 seconds every request finds no usable credential. What the client sees is this:

auth_unavailable: no auth available

Five retries all land inside the cooldown window, and the whole run dies.

At 2 it just works. The account rests for only two seconds, so the client's retry cadence lands right on the moment the cooldown ends — the second attempt goes through. I have not hit a full-run failure since.

4️⃣ secret-key → your admin password

Find secret-key and set an admin password:

secret-key: "your-admin-password"

This password is what you use to sign in to the CPA management console — keep it somewhere safe.

You can also fill in models, keys, and auth details directly in the config file, but the configuration is more involved. It is easier to start the service and work through the web console.

---

Step 3: Start the Service (With Silent Background Tip)

Open PowerShell in the CLIProxyAPI folder and run:

cli-proxy-api.exe

If you run it directly, leave this terminal window open — closing it stops the proxy.

💡 Power Tip: How to run it silently in the background?
If you do not want a console window sitting on your taskbar, create a text file named start-silent.vbs in the extracted folder with the following code:

CreateObject("WScript.Shell").Run "cli-proxy-api.exe", 0, False

Double-clicking this .vbs file launches the proxy completely silently in the background. To shut it down later, terminate cli-proxy-api.exe from Windows Task Manager.

---

Step 4: Open the Management Console

Once the service is running, open this in your browser:

http://127.0.0.1:8317/management.html

Enter the secret-key you set earlier to get in.

---

Step 5: Configure a Network Proxy

If your local network cannot reach the relevant AI services, fix it with one of these two approaches.

Option 1: turn on TUN mode. Enable TUN mode in your local proxy client so CPA's requests go through it automatically. This is the least work.

Option 2: configure a proxy inside CPA. Go to Config panel → Network settings and enter your local proxy address:

http://127.0.0.1:7890

Or:

socks5://127.0.0.1:7890

Use whatever port your local proxy client is actually configured for.

---

Step 6: Import the Codex Account with OAuth

CPA supports three ways to connect:

Method	What it suits
AI provider	Enter an official API Key
Auth file	Import an existing auth file
OAuth sign-in	Authorize the account through a browser — pick this for personal use

For personal use, choose OAuth sign-in.

In the CPA management console, select Codex OAuth and start signing in:

Once authorization succeeds, the account you just signed in with appears under Auth files as enabled:

If you need to manage more than one account, just repeat these steps.

---

Step 7: Connect Claude Code with CC Switch

Open CC Switch and create a new Claude Code provider entry:

• API Key: one of the keys you set under api-keys in step 2
• Request endpoint: http://127.0.0.1:8317

Then configure the model. Enter a model name your Codex subscription can call — mine was gpt6luna:

With that filled in, enable the provider and start Claude Code.

---

Advanced: Connect NextChat, Cherry Studio, or Any OpenAI Client

CLIProxyAPI isn't just for Claude Code — it functions as a standard local OpenAI-compatible API proxy. You can connect your Codex subscription to any client that accepts a custom endpoint and key (e.g. NextChat, Cherry Studio, Chatbox, Cursor, LibreChat):

Field	Value	Notes
API Base URL	http://127.0.0.1:8317/v1	Most OpenAI-compatible clients require the /v1 path
API Key	Your key from config.yaml	E.g. sk-codex-local, matching your configuration
Model Name	Active model in Auth files	E.g. gpt6luna, or whichever model name appears in your management console

Once configured, your client can talk directly to Codex without consuming official token credits.

---

Verify the Connection & Troubleshooting

Send anything in Claude Code — ask it to name the model it is currently using, for example. If it answers normally, you are connected: the step that used to block you on signing into an overseas account no longer appears.

If it does not work, match your symptom below:

Symptom / Error	Root Cause	Solution
Connection refused / ECONNREFUSED	Proxy service not running	Check if the terminal window closed, or verify cli-proxy-api.exe is running in Task Manager
401 Unauthorized / Auth failure	Key mismatch	Ensure your client's API Key exactly matches api-keys in config.yaml
auth_unavailable: no auth available	Upstream cooldown triggered by network blip	Essential: In step 2, change transient-error-cooldown-seconds to 2 and restart the service
Model not found	Incorrect model identifier	Check Auth files in the management console for the exact model name; do not copy blindly
Request timeout / hanging	Proxy connection failed	Revisit step 5; ensure your local proxy is running on the right port (e.g. 127.0.0.1:7890) or enable TUN mode

---

Frequently Asked Questions FAQ

Why must host be changed to 127.0.0.1?

The default is empty, which makes the service listen on every network interface on the machine. If you have a public IP at home, or you are on a corporate network, you have just exposed a model endpoint that anyone can call without a password. Setting it to 127.0.0.1 restricts access to the local machine — this is the first thing you must do.

Can I set only one value in api-keys?

Yes, but remember to comment out the other two default keys in the config file. A default key left in place is a backdoor — anyone can use it to call your account. It is also worth writing it in the sk- format. That is not enforced, but many clients check for it by convention.

Why change transient-error-cooldown-seconds from 0 to 2?

A default of 0 follows the old rule described in the config file's comments: a single 408, 500, 502, or 503 from upstream puts that account to sleep for 60 seconds. Network hiccups are common, so one blip sends the account into cooldown, and for those 60 seconds every request finds no usable credential (triggering auth_unavailable: no auth available) — the whole run fails. At 2 seconds the account only rests for two seconds, and the client's retry cadence lands right as the cooldown ends.

Can I connect more than one Codex account?

Yes. Repeat the OAuth sign-in flow in the management console to add more, and the auth files will list every enabled account. If one is in cooldown, requests fall through to the others automatically.

What model name do I enter when connecting Claude Code?

Use whatever the management console shows. Different Codex plan tiers expose different models — enter what you see in the auth file or model list. Do not copy a name out of someone else's tutorial: step 7 here used gpt6luna, and a different account may well be something else.

---

Related Guides

• CC Switch: Connect Claude Code Step-by-Step — the model-switching tool used in step 7, with installation and full usage
• Codex Tutorial — get value out of the Codex subscription you already have
• ChatGPT Plan Comparison — work out which tier your Codex quota belongs to
• Claude Tutorials Hub — what else you can do with Claude beyond Claude Code

Summary

What CLIProxyAPI does is turn a subscription account into a local API Key. The chain is: subscription account → local proxy service → API Key → client.

Seven steps in all: download and extract → change four config values → start the service → open the management console → configure a proxy → import the account over OAuth → connect with CC Switch.

The two easiest things to miss: renaming config.example.yaml to config.yaml, and setting host to 127.0.0.1. The easiest thing to trip over is the cooldown — the default of 0 freezes the account for 60 seconds at the first blip; change it to 2 and everything runs smoothly.