Let me conclude first: Just because Claude Code can be started and can answer a sentence does not mean that the third-party gateway is fully compatible. At least the Messages path, continuous streaming output, real tool calls, long context, error forwarding and usage records must be accepted separately to judge whether it is suitable for daily development.
This article comes from the issue classification of V2EX high discussion topics and GitHub Issues, and then uses Claude Code official gateway protocol and HTTP standards to correct it one by one. The number of forum views can only indicate the community’s attention.Not equivalent to search volume, probability of failure, or product conclusions。
Eight types of recurring problems in the community
In discussions related to Claude Code and third-party gateways, questions usually focus on the following eight categories:
| question | What users see | What levels really need to be checked |
|---|---|---|
| Protocol or path mismatch | 404、endpoint mismatch、/v1/v1 |
Base URL, Anthropic Messages path, client splicing rules |
| Streaming response exception | No output for a long time, disconnected midway, and finally appears all at once. | Whether SSE events are transparently transmitted segment by segment, and whether the reverse proxy buffers |
| Authentication failed | 401, 403, the web page can be used but the CLI cannot be used | Authentication variables, request headers, Key permissions and source restrictions |
| rate limiting or upstream failure | 429, 502, recovery after occasional retries | Quotas, concurrency, gateway retries, upstream errors and Retry-After |
| Broken tool call | Ordinary chat is normal, but reading files or executing commands fails. | tool definition,tool_use / tool_result with streaming events |
| Long context failed | Small tasks work, but analysis of a large repository fails or is truncated. | Request body limits, context windows, proxy timeouts, and model routing |
| Caching and billing exceptions | Cache miss, difficulty in correspondence between token and bill | cache fields,usage, request log and billing caliber |
| Unclear security boundaries | Source code, environment variables or credentials pass through an unknown gateway | Temporary keys, test repositories, tool authorization and data retention rules |
This table is a classification of problems and does not mean that these failures will occur in every transit service. A single anomaly cannot directly prove that the model has been replaced or "downgraded".
First confirm the protocol and final request path
Claude Code natively uses Anthropic Messages semantics. The official gateway protocol defines the inference entrance as /v1/messages, the optional Token counting entry is /v1/messages/count_tokens. OpenAI Chat Completions /v1/chat/completions Not the same agreement.
The correct link should be:
Claude Code
-> Authentication variables and Base URL
-> The gateway finally receives POST /v1/messages
-> The gateway forwards the request to the upstream
-> SSE Events continue to return Claude CodeDon't see it in the document /v1/messages, just append it to ANTHROPIC_BASE_URL. Different services have different conventions on whether the Base URL already contains the version path. Ultimately, the current access document of the service provider should prevail. Be sure to confirm when troubleshootingThe actual final URL received by the gateway, key points to exclude:
/v1/v1/messages: Base URL is repeatedly spliced with the client version path./v1/chat/completions: The OpenAI Chat entry was mistakenly handed over to the Anthropic client.- Returning HTML login page: The request fell to the console or website route, not the API route.
- The authentication header after 301 and 302 is lost: the Base URL has a cross-domain jump that should not occur.
When checking environment variables, do not print the full Key to the terminal history or screenshot:
for name in ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY; do
eval "value=\${$name}"
if [ -n "$value" ]; then
printf '%s=<Already set>\n' "$name"
else
printf '%s=<not set>\n' "$name"
fi
doneIf multiple authentication variables are set at the same time, the required items should be retained according to Claude Code official documents and service provider instructions to avoid ambiguity between the old Key and the new Key.
Complete six acceptance checks in 20 minutes
Use a test repository without customer data and a separate low-limit key. Complete each step before moving on, and do not start with a long-running task.
1. Minimal read-only tasks
To run Claude Code in the test directory, enter:
Only read the current directory README，Do not modify files。Return file title、Number of first-level titles and three content summaries。Passing criteria: The request can be completed; the file title is consistent with the actual content; there is no unauthorized modification of the file. Save time, model ID, HTTP status code, and request ID.
2. Continuous streaming output
Enter a task that is enough to produce multiple pieces of output but does not consume a large amount of Tokens:
According to README generate 12 Pre-launch checklist，Each item contains inspection actions and passing criteria。Passing criteria: Content appears gradually, rather than returning all at once after a long blank period. The official protocol requires that inference responses remain streaming; if a gateway or reverse proxy buffers the full response, the client may behave as if it is stuck or timing out.
3. A real tool call
Input:
read package.json，tell me scripts How many commands are there in，and itemize the names。Do not modify the file。Passing Criteria: Claude Code actually reads the file and the results can be checked against the file. Just asking the model to interpret a piece of pasted text cannot verify the tool call chain.
4. Write tasks that can be rolled back
In the temporary branch or temporary directory enter:
New gateway-check.txt，Just write one line GATEWAY_CHECK_OK，Then read the file confirmation content。Do not modify other files。Passing criteria: Creation, reading and result reporting are all correct;git diff Only expected files appear. Delete the test files when finished.
5. Add context step by step
Let Claude Code summarize 1 file first, then expand to 5 related files, and finally test module-level tasks. At which level records begin to appear 400, 413, 502, truncated or glaringly omitted.
Don't use a single extreme context test to conclude "how many K's are supported". The actual context available is also affected by the model, system prompts, tool results, gateway request body limits, and timeouts.
6. Check usage, cache and billing
Find the above request in the console or gateway log and check the request model, response model, input/output token, cache read/write fields, chargeback and request ID. Missing fields do not necessarily mean an error, but you must confirm what billing method the service provider uses.
Repeating the same small task three times at different times has more judgment value than keeping only one successful screenshot. Do not conduct high-concurrency stress testing in pursuit of sample size unless explicitly permitted by the service provider.
Locate 403, 429, 502 and tool errors according to the phenomenon
| phenomenon | Priority check | Don't do anything first |
|---|---|---|
| 404 / endpoint mismatch | The final URL, whether it is /v1/messages, whether to repeat /v1 |
Repeatedly change API Key |
| 401 | Whether the Key exists, authentication variable name, authentication header format, whether the Key is revoked | Send the complete Key to the group chat for help |
| 403 | Key permissions, model permissions, source/IP policies, terms of service restrictions | The default judgment is that the model is offline. |
| 429 | Account quota, Key limit, concurrency,Retry-After, retreat strategy |
Immediately retry infinitely |
| 502 / Cut off midway | Upstream errors, gateway logs, request IDs, proxy timeouts, and response buffering | Judge long-term stability only by one failure |
| 400 / Extra inputs | Whether the gateway discards or rejects the new Claude Code field and whether the beta header is transparently transmitted | Fixed request field no longer updating after whitelisting |
| Chat is normal but tool fails | Tool definition, tool event,tool_result, Is the streaming JSON complete? |
Successfully replaced Agent acceptance with normal dialogue |
| Stuck after calling tool | Tool result return, event sequence, end event, gateway error text | Only increase client timeout |
| Fails with long context | Request body size, context upper limit, proxy timeout, routing model changes | Direct promotion fixed context cap |
| Cache or chargeback exception | usage, cache fields, request logs, billing time window |
Token is estimated only based on the number of words output. |
Claude Code continues to evolve request fields and beta capabilities. If the gateway only accepts a fixed field whitelist, 400 may suddenly appear after the client is updated. A more reliable implementation is to forward supported fields and headers according to the official protocol, and retain the upstream error status, error body, and request ID to facilitate client retry and manual location.
Models, caches, contexts and security boundaries
No need to judge a single style change to change the model
in response model Fields, output styles, and knowledge questions all provide only part of the signal. To troubleshoot route replacement or capability degradation, tasks, parameters, and time windows should be fixed, and multiple rounds of comparisons should be conducted based on model declarations, tokens, tool calls, SSE, dynamic questions, and real business baselines. Can continue readingmodel quality degradation detection methodandModel field authenticity description。
Cache hits should be viewed together with request logs
Caching performance is affected by prompt word prefixes, tool definitions, context changes, model and gateway support range. Just comparing two bill amounts doesn't prove whether caching is working. The request ID should be saved and compared to usage Cache fields and console records publicly supported by Chinese service providers.
Give Agent a smaller permission area
- Use an independent, revocable, limited test key that is not shared with production services.
- Validate with public samples or a redacted repository first. Do not upload customer code, production logs, or
.env。 - The automatic authorization mode that skips confirmation is not enabled before the gateway's data processing and retention rules are confirmed.
- Keep in test repository
.gitignore, command whitelisting and manual confirmation steps. - Only a few desensitized characters before and after the Key are retained in the report; public screenshots should cover request headers, environment variables and internal addresses.
Save the acceptance record and select Next
Copy the template below and run it again every time you upgrade Claude Code, switch models, or change gateways:
Test date：____________________
Claude Code version：____________
Gateway name：____________________
Base URL（Desensitization）：____________
request model / response model：_________
[ ] Minimal read-only task passed
[ ] Continuous streaming output passes
[ ] Real tool calls pass
[ ] Rollback write tasks pass
[ ] Graded context test passed
[ ] usage / cache / Bills can be verified
HTTP status code：_________________
Request ID：_____________________
Failure steps and minimum recurrence：__________
Retest time and results：______________Select the entrance based on the current stage:
- Still troubleshooting: ViewClaude Code configuration tutorial、SSE streaming output tutorialandAPI error troubleshooting。
- Need to compare OpenAI Compatible entry: UseFree model and API gateway detection tool. The tool currently checks for OpenAI Chat Completions compatibility endpoints,Anthropic Messages entry cannot be verified directly。
- Ready to access: View firstCurrent models and prices, and then confirm the Claude Code special agreement and address according to the current document of the service provider.
- Prepare to create a test key: Register AIFast, use independent Key to start acceptance from short tasks.
If the service provider only provides OpenAI Chat Completions, it cannot be regarded as fully compatible with Claude Code just because the model name contains Claude. Protocol, tool, streaming and billing fields should be accepted separately.