网关与协议

Claude Code 可以通过 ANTHROPIC_BASE_URL 接入 LLM gateway。Gushen888 就属于这类 Claude Code 入口:本地 CLI 仍按 Anthropic Messages 格式发请求,网关负责转发、鉴权、模型路由、计费和观测。

Claude Code 使用 https://api.gushen888.cloud,不带 /v1。OpenAI 兼容客户端和 Codex 才使用 https://api.gushen888.cloud/v1。

如果你只是配置客户端,看本页和 Provider 认证与云平台接入。如果你要实现或验收网关,看 Gateway 协议上线清单。

最小接入

export ANTHROPIC_BASE_URL="https://api.gushen888.cloud"
export ANTHROPIC_AUTH_TOKEN="sk-你的 Gushen888 API Key"
claude -p "只回答 ok"

Windows PowerShell:

$env:ANTHROPIC_BASE_URL = "https://api.gushen888.cloud"
$env:ANTHROPIC_AUTH_TOKEN = "sk-你的 Gushen888 API Key"
claude -p "只回答 ok"

推荐把 Key 放在用户级 settings 或本机环境变量,不要提交到项目仓库:

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.gushen888.cloud",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的 Gushen888 API Key"
  }
}

请求格式

Claude Code 对 ANTHROPIC_BASE_URL 使用 Anthropic Messages 格式:

项目	说明
主要端点	`/v1/messages`
可选端点	`/v1/messages/count_tokens`
认证	`Authorization: Bearer ...` 或 `x-api-key`
流式	必须支持 SSE 流式转发
模型列表	可选 `/v1/models?limit=1000`

如果网关把 Anthropic Messages 请求转到 Bedrock、Vertex 或其他 schema,转换是网关责任。客户端不要把 Claude Code 的 Base URL 写成 OpenAI /v1。

必须透传的内容

官方协议强调 gateway 不应该用固定白名单剥字段。Claude Code 的能力会随版本增加,字段和 beta header 会变。

内容	为什么重要
`anthropic-version`	上游 API 版本
`anthropic-beta`	tool search、context management、extended context、beta tool fields 等能力
`system` array 顺序	attribution block、system prompt 和缓存 key 依赖它
`tools` / tool schema	MCP、内置工具、deferred tool loading
`thinking`	adaptive reasoning
`output_config`	effort、structured output、task budget
`context_management`	自动上下文管理能力
错误 body	Claude Code 会根据上游错误文字做自动 retry 或能力降级

如果网关要做安全审计,应读取但不要重写 request body。剥 header、改 system array、把 system 合并成字符串,都会影响能力或 prompt cache。

Attribution block 与缓存

Claude Code 会在 system prompt 前放一个 attribution block。直接发到 Anthropic API 时,官方 endpoint 会在位置正确时剥掉它,避免影响 first-party prompt cache。

自定义网关要注意:

做法	结果
原样转发 `system` array,保持 attribution block 第一项	最稳
在前面插入自己的 system block	可能导致 attribution block 进入模型 prompt 和 cache key
把 system array 合并成字符串	可能破坏 strip 和缓存
网关必须改写 system	客户端可考虑 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`

官方说明从 Claude Code v2.1.181 起,自定义 Base URL 下 attribution block 在一个 conversation 生命周期内更稳定,对 gateway-side full body cache 更友好。旧版本如果网关自己按请求体做缓存,可能需要禁用 attribution header。

Prompt Cache 与 Gushen888

Gushen888 下排查缓存,看三层:

层	检查
Claude Code 客户端	是否频繁 `/model`、`/effort`、`/fast`、`/compact`、升级 CLI
网关	是否透传 cache-control、beta headers、tools、usage 字段
上游模型	是否支持 prompt caching、tool search、1h TTL、context window

usage 字段:

字段	含义
`cache_creation_input_tokens`	本轮写入缓存的输入 token
`cache_read_input_tokens`	本轮从缓存读取的输入 token

读写比越高,缓存越健康。如果每轮 creation 都高,优先检查模型、effort、fast mode、MCP 工具定义、插件 MCP、整工具 deny 和 /compact。

模型发现

如果网关实现 /v1/models,Claude Code 可以把网关返回模型加入 /model picker。

启用:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

注意:

条件	说明
只适用于 `ANTHROPIC_BASE_URL`	Bedrock/Vertex/Foundry provider 变量优先时不会走这里
请求超时很短	`/v1/models` 慢或重定向会静默失败
结果会缓存	本机缓存文件在 `~/.claude/cache/gateway-models.json`
自定义模型能力	模型出现在 picker 不代表 effort、tool search、1M context 都可用

常见错误

现象	可能原因	修复
`401`	Key 错、header 不匹配、旧登录冲突	确认 `ANTHROPIC_AUTH_TOKEN`,必要时 `/logout`
`ConnectionRefused`	Base URL 错、VPN/防火墙拦截	用 curl 直接测网关
HTTP 200 但响应 malformed	网关返回 HTML 登录页或代理错误页	修正路由,确保 `/v1/messages` 返回 API JSON/SSE
`400 context_management`	网关转发到不支持该字段的上游	透传到支持上游,或临时 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`
`400 thinking` / `adaptive`	上游模型不支持 adaptive reasoning	升级上游或按官方变量禁用对应能力
模型列表缺失	`/v1/models` 未实现或发现未开启	开启 discovery 或手动写模型
Remote Control 不可用	自定义 gateway credential 或非 Anthropic base URL	见网页与远程控制
官方账号能力不出现	当前 provider 不是 claude.ai subscription 或 Anthropic API	见功能可用性
`/context` 估算不准	`count_tokens` 端点缺失	实现 token counting 或接受本地估算

企业配置

企业/团队可以用:

能力	用途
Managed settings	下发 Base URL、模型 allowlist、permissions、hooks
Server-managed settings	让 web/cloud/desktop cloud sessions 也接收组织策略
`apiKeyHelper`	动态取网关 token,避免静态 Key
`ANTHROPIC_CUSTOM_HEADERS`	加租户、路由、审计 header
OpenTelemetry	观测 Claude Code usage、tool、hook 和 cost
网关 spend limits	网关侧限制个人日/周/月用量

apiKeyHelper 输出通常会缓存一段时间。官方示例可以用 CLAUDE_CODE_API_KEY_HELPER_TTL_MS 调整缓存时长。

如果要自托管 Claude apps gateway 或运维通用 Anthropic-compatible gateway,继续看 Gateway 运维和 Claude apps gateway 部署。那里单独展开 OIDC、Postgres、spend limits、模型发现、协议透传和 1 小时缓存 TTL 的网关边界。

Gushen888 建议清单

Base URL 写 https://api.gushen888.cloud,不要 /v1。
用 ANTHROPIC_AUTH_TOKEN,不要混用多个认证变量。
长任务开局先定 /model、/effort、是否 /fast。
如果 MCP 多,优先确认 tool search 和 deferred tools。
如果 cache read 一直为 0,先用无 MCP、固定模型、固定 effort 的长会话复测。
如果模型不在 picker,先确认后台实际模型 ID,再考虑 gateway model discovery。
如果 Remote Control 或 voice dictation 不可用,先暂时移除 gateway 变量确认边界。

网关与协议

最小接入

请求格式

必须透传的内容

Attribution block 与缓存

Prompt Cache 与 Gushen888

模型发现

常见错误

企业配置

Gushen888 建议清单

官方参考

相关页面

网关与协议 ​

最小接入 ​

请求格式 ​

必须透传的内容 ​

Attribution block 与缓存 ​

Prompt Cache 与 Gushen888 ​

模型发现 ​

常见错误 ​

企业配置 ​

Gushen888 建议清单 ​

官方参考 ​

相关页面 ​

网关与协议

最小接入

请求格式

必须透传的内容

Attribution block 与缓存

Prompt Cache 与 Gushen888

模型发现

常见错误

企业配置

Gushen888 建议清单

官方参考

相关页面