When something breaks
- Author
- Ethan Pier
- Series
- Notes from use
Start here.
The relay forwards your request. It does not open a terminal on your machine, read your files, or push git for you. A shell, file reads, and commands are tools that the client registers — Codex, Claude Code, and the rest. A reply only means that one call went through.
Each section ends with a step you can take yourself. Keys in here are the fake value sk-xxxx. Don't paste a real key into chat, a screenshot, or a ticket.
Signing in
The entrance is https://api.cloudborne.cn/login. Use the relay account's email and password. Calls use a key created inside that account.
The base URL is wrong
Codex and other OpenAI-compatible clients take the base URL through /v1: https://api.cloudborne.cn/v1. Don't use the bare origin https://api.cloudborne.cn. Don't add a trailing slash.
Claude Code uses the origin, without /v1. It reads ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, not the OpenAI URL above.
Opening https://api.cloudborne.cn/v1/models with no key returns 401. That's expected. It means the URL is up, and it wants a credential.
401, 403, balance
Read the status before you change config.
- 401: the key is wrong, disabled, or an old process is still holding the old key. Check the current key on the keys page, then quit the client completely and open it again.
- 403: balance, group, or this key is not allowed to call that model. A zero balance blocks the call outright.
- The key is shown once. After you close the create dialog, the full value is gone. You can't recover it. Disable the old one and create another.
- A leaked key is the same move: disable it, create a new one, update the client, delete the string from wherever it was posted. If you can't delete it, treat it as leaked and stop using the old key.
Screenshots and tickets only show sk-xxxx. Cover the email, the balance, and the key.
There is a reply, and no terminal
The model answered. You asked it to run Get-Location. It listed the tools it can see, then refused to pretend it ran one. The names look like functions.functions__request_user_input_async, functions.clock__sleep, functions.collaboration__send_message. So it also can't push to GitLab, or edit a file.
Those names are collaboration tools the client sent up. They are not a shell. request_user_input_async only asks you a question. The relay will not insert exec into that list, and it will not read your disk.
What to do:
- Quit Codex Desktop or the CLI completely. Closing the window is not enough — a live process keeps the old tool registry.
- Start a new task. Don't reuse the one you just had.
- Look for
execin the new tool list.
If exec is still missing after a restart, this client never registered a shell or file reads. Use a client that does, or turn those tools on in this one. The relay forwards the tool list it received. It does not add capabilities your machine didn't send.
Protocol mismatch
Responses and Chat Completions are two different roads. Don't mix them.
Codex uses Responses: https://api.cloudborne.cn/v1, format set to Responses.
A DeepSeek group in Claude Code uses Chat Completions. Sonnet, Opus, and Haiku inside Claude Code are local slots, not upstream model ids. For that group, start with:
| Claude Code slot | Model id |
|---|---|
| Sonnet | deepseek-v4-flash |
| Opus | deepseek-v4-pro |
| Haiku | deepseek-v4-flash |
If the group only serves DeepSeek, don't point the three slots at another vendor unless you have already completed a call to those models in this group.
HTTP 200, but the usage page shows 0 tokens and 0 cost, or the stream ends in a failure: treat it as the wrong protocol. Switch to the format in the table, make one short call, then check the usage page for a non-zero row.
Grok CLI needs api_backend = "responses". Leave it unset and it defaults to /v1/chat/completions.
The new config never applied
After CC Switch changes the provider to Cloudborne, Codex does not pick the new config up on its own.
- Confirm the active provider is Cloudborne and the target app is Codex.
- Close the current Codex session.
- Open a new terminal, then start Codex.
In the preview, base_url should be https://api.cloudborne.cn/v1.
Claude Code hot-reloads. That's the exception — you usually don't restart it just to swap a key. Other clients do.
Model names come from the relay console, or from Fetch Models in CC Switch. Don't copy a model id out of someone else's tutorial.
Reasoning field errors
If the error mentions reasoning_content, it's usually one of two things:
- A tool-calling turn sent the next message without that field, and the upstream returned 400.
- An OpenAI-format client hit an upstream that requires the thinking field, and the fields don't line up.
Confirm the client's format and this group are the same protocol. DeepSeek with Claude Code goes back to Chat Completions and the three-slot mapping above. Don't retry on the same key with both formats mixed together.
Slow first token, 502, overloaded
Separate three cases.
When a model is down, check that vendor's status page before changing the base URL or the key.
-
The first token takes a long time, or you see
502 timeout awaiting response headers: the request left, and it's waiting on the upstream. Try one short call. If a short call does the same thing and the protocol and model name are right, this is not the base URL. -
overloaded, or the server says it is overloaded: the upstream is refusing new work. Wait, then try again. Don't keep resending the same long request. -
The public homepage opens and the client doesn't: check the local proxy, VPN, and office network. Open
https://api.cloudborne.cn/in a browser. Homepage up, calls down — go back to the base URL and the key.
A successful response with 0 usage belongs under "Protocol mismatch," not under timeouts.
Web search returns 404
Codex's built-in web search calls a path like POST /v1/alpha/search. The relay has no such route, so it returns 404. The key is not bad, and the balance is not the cause.
Chat and completions still go through /v1. Treat search as the client's own feature: this relay does not serve that search URL.