ClipProxy login: one OAuth command per provider, then point your tools at it
ClipProxy (the upstream project is CLIProxyAPI) does not have its own username and password. You log in to each provider with a single command, the proxy stores the token, and then it re-serves your subscription as a local API. Below is the exact flow, how to confirm it worked, and the part most write-ups leave out: feeding a logged-in ClipProxy into a native Mac agent instead of a terminal.
To log into ClipProxy, run the login command for the provider you want, then approve the OAuth screen in your browser:
clipproxyapi --claude-login # Anthropic / Claude Code clipproxyapi --codex-login # OpenAI / ChatGPT Codex clipproxyapi --gemini-login # Google / Gemini CLI # headless box with no browser: clipproxyapi --claude-login --no-browser
The token JSON is written to ~/.cli-proxy-api/ and the proxy then serves on http://localhost:8317. Source: router-for-me/CLIProxyAPI.
Login command for each provider
There is no single login screen. Each provider has its own flag, and you can repeat the process to stack several accounts in the same proxy.
| Provider | Command | Notes |
|---|---|---|
| Claude Code (Anthropic) | clipproxyapi --claude-login | Subscription OAuth, token good ~1 week |
| ChatGPT Codex (OpenAI) | clipproxyapi --codex-login | OpenAI OAuth consent flow |
| Gemini CLI (Google) | clipproxyapi --gemini-login | Auto-refresh; fails only if revoked |
| Any of the above, headless | <command> --no-browser | Prints the OAuth URL instead of opening a browser |
Token lifespans differ. Claude subscription tokens last roughly a week, so you re-run --claude-login when requests start returning auth errors.
The full login, step by step
What actually happens between typing the command and having a working local endpoint.
Run the provider login command
clipproxyapi --claude-login. The proxy starts a short-lived local callback listener and opens your default browser to the provider's OAuth consent page.
Approve in the browser
You sign in with your normal account (the same one your subscription is on) and grant access. On a headless box, add --no-browser and the OAuth URL is printed so you can open it elsewhere.
Token is written to ~/.cli-proxy-api/
The proxy captures the OAuth callback and saves a JSON token file in the auth directory. The running server watches that folder and hot-reloads, so no restart is needed to pick up a new account.
Proxy serves on http://localhost:8317
Any client that speaks the OpenAI, Anthropic, or Gemini API format can now hit that base URL and get answers from your subscription, with no separate API key purchase.
Point a real tool at it
A curl command proves it works. The more useful move is wiring the endpoint into an app you actually use all day, covered in the next section.
Confirm the login took
A login that opened a browser is not proof of a working endpoint. Check these three things before you wire anything else up.
Login is good when
- A JSON token file exists in ~/.cli-proxy-api/ for the provider you logged in with.
- curl http://localhost:8317/v1/models returns a model list instead of a connection refused.
- A test chat completion against http://localhost:8317 returns content, not a 401 or 403.
# is the proxy answering on its port? curl http://localhost:8317/v1/models # did the token actually land? ls ~/.cli-proxy-api/
The step the other guides skip: using your logged-in proxy in a GUI
Most write-ups stop at "you now have an OpenAI-compatible API." That leaves you back in a terminal piping curl. The point of logging in once is to run your subscription through tools you live in. The flow below is how that endpoint reaches a native macOS agent.
From ClipProxy login to a working Mac agent
Browser OAuth
clipproxyapi --claude-login
Token stored
~/.cli-proxy-api/*.json
Local endpoint
http://localhost:8317
App custom endpoint
ANTHROPIC_BASE_URL set for you
GUI agent runs
subscription, in a Mac app
In Fazm, the open-source native macOS app this site documents, you paste http://localhost:8317 into Settings, Advanced, AI Chat, Custom API Endpoint. Fazm wraps the real Claude Code agent loop, so the endpoint you set is exactly what that agent process talks to.
What the app actually injects (and why a typo can't break it)
This is the uncopyable detail, and it is checkable in the open-source repo. When you set a custom endpoint, Fazm does not just forward the string. In Desktop/Sources/Chat/ACPBridge.swift it injects two environment variables into the spawned Claude agent: it sets ANTHROPIC_BASE_URL to your endpoint, and it replaces the bundled subscription key with a deliberate placeholder so your proxy never receives Fazm's own key.
env["ANTHROPIC_BASE_URL"] = customEndpoint // your http://localhost:8317 env["FAZM_CUSTOM_API_ENDPOINT"] = "true" // never send the bundled key to your proxy: env["ANTHROPIC_API_KEY"] = "sk-fazm-custom-endpoint"
That placeholder, the literal string sk-fazm-custom-endpoint, keeps Anthropic-compatible local gateways on the API-key path instead of triggering a fresh OAuth dance. And before any of this runs, a guard named validCustomAPIEndpoint rejects any value that is not an absolute http or https URL with a host. A bare localhost:8317 with no scheme is dropped and the app falls back to the default, rather than landing a broken value in ANTHROPIC_BASE_URL and throwing Invalid URL on every message. So the only thing that has to be right is the proxy port from your login, and a missing http:// fails safe instead of silently bricking chat.
Common login problems
Browser never opens. You are on a headless or SSH session. Re-run with --no-browser and open the printed URL on a machine that has a browser.
Worked yesterday, 401 today. The provider token expired. Claude subscription tokens are good for about a week; just re-run the login command and the watched auth directory hot-reloads the new token.
Connection refused on 8317. The proxy process is not running, or it is bound to a different port in config.yaml. Start the server and confirm the port before pointing a client at it.
Want your subscription driving a real Mac agent, not just curl?
Walk through wiring a logged-in proxy into a native macOS agent that also reaches the browser and your apps.
Questions about ClipProxy login
Frequently asked questions
What is the ClipProxy login command?
There is one login command per provider. For Anthropic it is clipproxyapi --claude-login, for OpenAI it is clipproxyapi --codex-login, and for Google it is clipproxyapi --gemini-login. Each one opens your browser to the provider's normal OAuth consent screen, you approve, and the command writes a token file. There is no username and password field on ClipProxy itself, the login is delegated to whichever provider you are authenticating against. ClipProxy (the project is named CLIProxyAPI upstream) is the local proxy that holds those tokens and re-exposes them as an OpenAI-compatible API.
Where does ClipProxy store the login token after I sign in?
In the ~/.cli-proxy-api/ directory in your home folder, as a JSON file per account. The running server watches that directory and hot-reloads tokens when the files change, so you can add or rotate an account without restarting the proxy. If you delete the JSON file you are effectively logged out and the next request for that provider fails until you run the login command again.
How do I log into ClipProxy on a headless server with no browser?
Add the --no-browser flag to the login command, for example clipproxyapi --claude-login --no-browser. Instead of opening a browser the proxy prints the OAuth URL to the terminal. You copy that URL, open it in a browser on any machine, complete the consent, and the proxy captures the resulting token. This is the path for VPS, Docker, and SSH sessions where there is no local browser to launch.
What port does ClipProxy run on after login?
Port 8317 by default. Once you are logged in the proxy listens on http://localhost:8317 and answers OpenAI-, Anthropic-, and Gemini-compatible requests. You point any client that speaks one of those API formats at that base URL. The port and other behavior live in a config.yaml that the proxy reads from the same auth directory.
Does ClipProxy login use my Claude subscription or API credits?
It uses your subscription. The whole point of the --claude-login flow is that it authenticates with the same OAuth session your Claude Code subscription uses, so requests through the proxy draw from your Pro or Max plan rather than billing per-token API credits. That is also why the Claude token is short-lived (roughly a week) and you re-run the login when it expires, the same as the underlying CLI.
How do I use a logged-in ClipProxy inside a desktop app instead of a terminal?
Point the app's custom endpoint setting at http://localhost:8317. In Fazm, the native macOS agent this site documents, that field is under Settings, Advanced, AI Chat, Custom API Endpoint. Fazm validates the URL, injects it as ANTHROPIC_BASE_URL into the Claude agent process, and disables its own bundled key so the request flows through your proxy. After that, your subscription, authenticated once via ClipProxy login, drives a GUI agent that can also reach the browser and other Mac apps, not just a curl command.
Why does my request work in curl but fail inside the app?
Almost always a malformed endpoint URL. ANTHROPIC_BASE_URL must be an absolute http or https URL with a host, like http://localhost:8317. A value like localhost:8317 (no scheme) or stray text gets rejected, and a naive wrapper that forwards it anyway makes the SDK throw Invalid URL on every call. Fazm guards against this: its validCustomAPIEndpoint check rejects anything that is not a real http(s) URL with a host and falls back to the default rather than bricking chat. So if the proxy works in curl but not in the app, re-check the exact string you typed, including the scheme.
Endpoints, cost, and the layer above the CLI
Adjacent reading
ANTHROPIC_BASE_URL: routing Claude Code through a custom endpoint
The variable is read once, at process spawn. Why a running agent ignores a change, and how a GUI injects it for you.
AI coding: API credits vs subscription tools
When per-token API billing beats a flat subscription, and when a proxy that re-exposes your plan as an API is the cheaper path.
Controlling Claude Code context compaction
Auto-compaction silently drops decisions in long sessions. What you can control, and what a wrapper changes.
Comments (••)
Leave a comment to see what others are saying.Public and anonymous. No signup.