Claude Code 接入第三方模型
将本地 Claude Code 连接到第三方兼容 Anthropic 或 OpenAI 模型端点,支持实测模型名、环境变量优先级判定和多配置源排查。
Claude Code 接入第三方模型(Anthropic 兼容端点)
开源仓库:https://github.com/oracis/claude-code-third-party-model 本技能自带两个零依赖脚本(在
scripts/目录下):ccproxy.py—— Anthropic ↔ OpenAI 协议转换网关(纯标准库,约 1240 行);ccswitch.py—— 多 profile 一键切换 + 网关启停协调(跨平台,约 430 行)。 另有examples/profiles/提供开箱可用的settings.json模板。
核心思路
不要相信文档里的模型名,也不要猜哪份配置生效 —— 两件事都实测。
第三方文档经常出现旧模型名 / 别名混写(例如 DeepSeek 官方两版文档分别写
deepseek-flash 和 deepseek-v4-flash)。以服务端报错为准。
Step 1 · 实测真实模型 ID
先看账号可用清单:
curl -s https://api.deepseek.com/models -H "Authorization: Bearer $KEY"
再拿候选名逐个打 Anthropic 兼容端点(这才是权威,/models 常漏别名):
KEY=$(python -c "import json;print(json.load(open(r'C:/Users/<u>/.claude/settings.json'))['env']['ANTHROPIC_AUTH_TOKEN'])")
for M in "deepseek-flash" "deepseek-flash[1m]" "deepseek-v4-flash" "deepseek-chat" "deepseek-v4.1-flash"; do
printf '%-24s => ' "$M"
curl -s -m 45 https://api.deepseek.com/anthropic/v1/messages \
-H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
-d "{\"model\":\"$M\",\"max_tokens\":8,\"messages\":[{\"role\":\"user\",\"content\":\"hi\"}]}" \
| python -c "import sys,json;d=json.load(sys.stdin);print('OK ->',d['model'] if 'model' in d else 'ERR '+str(d.get('error',{}).get('message'))[:160])"
done
要点:
- 若本机设置了 HTTP 代理,curl 默认会经代理转发;给 curl 加
--noproxy声明直连目标 (如--noproxy api.deepseek.com),或按第五部分把目标列入no_proxy环境变量。 - 失败时报错信息会直接列出全部合法模型名,这是最快的权威来源。
- 成功时回显的
model字段是服务端归一化后的真名,能看出哪些是别名 (如deepseek-chat→ 回deepseek-v4-flash)。
已知别名关系(DeepSeek,2026-09 实测):
deepseek-flash=deepseek-v4-flash=deepseek-chat(同一模型,即 V4.1 Flash);deepseek-v4.1-flash不存在。
Step 2 · [1m] 后缀是什么
[1m] 不是模型名的一部分,是 Claude Code 本地的「上下文窗口声明」后缀,服务端会剥离
(发 deepseek-flash[1m] 回体是 "model":"deepseek-flash")。
- 不加:CC 按 200k 处理 auto-compact。
- 加:
modelUsage.contextWindow变 1000000。 - 模型不在 CC 内建目录时会打一行
[claude-code:unrecognized_model]到 stderr, 无害、不影响功能,CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1也消不掉, 别在这上面浪费时间。 - 更精细的控制用
CLAUDE_CODE_AUTO_COMPACT_WINDOW(DeepSeek 官方建议786432)。
Step 3 · 配置模板
~/.claude/settings.json(用户级、跨项目,是唯一真相源):
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "<KEY>",
"ANTHROPIC_MODEL": "deepseek-flash[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-flash[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL_NAME": "deepseek-flash",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-flash[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL_NAME": "deepseek-flash",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-flash",
"ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME": "deepseek-flash",
"ANTHROPIC_DEFAULT_FABLE_MODEL": "deepseek-flash[1m]",
"ANTHROPIC_DEFAULT_FABLE_MODEL_NAME": "deepseek-flash",
"CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-flash[1m]",
"CLAUDE_CODE_EFFORT_LEVEL": "max",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "786432",
"API_TIMEOUT_MS": "600000",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
},
"model": "deepseek-flash[1m]",
"tui": "fullscreen"
}
_MODEL_NAME 是显示名(不带 [1m]);_MODEL 是真正发给 API 的 ID。
DEFAULT_*_MODEL 让 /model opus|sonnet|haiku 都落到同一个模型。
Step 4 · 查真实支持的 env 变量名(别照抄博客)
Claude Code 现在是单文件 native 二进制(不是 js),直接从里面提取权威变量名:
B="$APPDATA/npm/node_modules/@anthropic-ai/claude-code/bin/claude.exe"
strings -n 6 "$B" | grep -ohE "ANTHROPIC_[A-Z_]+|CLAUDE_CODE_[A-Z0-9_]+|API_TIMEOUT_MS" | sort -u
(Windows 的 $APPDATA 在 Git Bash 下即 C:/Users/<u>/AppData/Roaming。)
值得注意的真实变量:ANTHROPIC_DEFAULT_FABLE_MODEL、
CLAUDE_CODE_{MAX_CONTEXT_TOKENS, AUTO_COMPACT_WINDOW, SUBAGENT_MODEL, EFFORT_LEVEL,
DISABLE_1M_CONTEXT, MODEL_CATALOG, MODEL_OVERRIDES...}。
Step 5 · 判定「哪份配置生效」—— 必须实测
优先级实测结论:settings.json 的 env 块 > 从 shell/系统继承的进程环境变量。
(官方文档那句「shell 导出的 ANTHROPIC_MODEL 优先于文件里的 model 键」说的是
model 键,不是 env 块,别被绕进去。)
验证方法(唯一可靠手段):跑一次带 JSON 输出的查询,读 modelUsage。
cd <项目目录> && claude -p "hi" --output-format json < /dev/null 2>&1 \
| tr -d '\r' | grep -o '"modelUsage":{.*' | head -c 600
看 canonicalModel 和 contextWindow 就知道真实生效的是什么。
验证子代理:提示里让它起一个 Agent,再 grep "canonicalModel":"..."。
Step 6 · 排查其它覆盖源(Windows)
依次查这些地方,任何一处都会造成「改了不生效」:
# 1) 用户/系统级持久环境变量(用 Python winreg 读,最省事)
python -c "
import winreg
for root,lab in ((winreg.HKEY_CURRENT_USER,'HKCU'),(winreg.HKEY_LOCAL_MACHINE,'HKLM')):
try:
k=winreg.OpenKey(root,r'Environment'); n=winreg.QueryInfoKey(k)[1]
for i in range(n):
nm,v,_=winreg.EnumValue(k,i)
if 'ANTHROPIC' in nm.upper() or 'CLAUDE' in nm.upper(): print(lab,nm,'=',v)
except FileNotFoundError: pass
"
# 2) 项目级覆盖(优先级高于用户级)
cat .claude/settings.json .claude/settings.local.json 2>/dev/null
# 3) ~/.claude.json 里的 model / env 字段
python -c "import json;d=json.load(open(r'C:/Users/<u>/.claude.json'));print({k:d[k] for k in ('model','env','primaryApiKey') if k in d})"
改 HKCU 环境变量后必须广播,否则已开着的资源管理器/终端读不到新值:
import ctypes
ctypes.windll.user32.SendMessageTimeoutW(0xFFFF, 0x1A, 0, ctypes.c_wchar_p('Environment'),
0x0002, 5000, ctypes.byref(ctypes.c_ulong()))
收尾清单
- 改前备份:
cp ~/.claude/settings.json ~/.claude/backups/settings.json.bak-$(date +%Y%m%d-%H%M%S); 若要动 HKCU,先把变量导出一份 json 到同目录。 - 改后必须跑 Step 5 验证主模型 + 子代理模型,不能只看配置文件。
- 报告里不要回显 API Key,只说前缀 + 长度。
- 收尾时用 Step 9 检查是否留下了重复配置源。
常见坑速查
| 现象 | 根因 |
|---|---|
报 invalid_request_error 且列出支持名 | 模型名错/不存在,用报错里列的名字 |
每次启动一行 [claude-code:unrecognized_model] | 正常,第三方模型都不在 CC 目录里 |
contextWindow 只有 200000 | 模型名忘了加 [1m] |
| 改了 settings.json 不生效 | 有 HKCU/项目级/.claude.json 覆盖,或没重启 CLI |
| 命令行读注册表不方便 | 直接用 Python winreg,无需外部程序 |
| PowerShell 有时 exit 0 但无输出 | 该环境下 stdout 未必回显,换 bash + python 排查更可靠 |
export ANTHROPIC_MODEL=... 后没变化 | settings.json 的 env 块优先级更高,见 Step 7 |
第二部分:接入后「变慢」怎么定位
不要猜。 慢只有四个来源:启动开销 / 网络 / 模型推理 / 交互感知。按下面顺序逐层排掉。
Step 7 · 先记住优先级铁律(决定了怎么切档)
claude --model / --effort 等命令行参数
> ~/.claude/settings.json 的 env 块
> shell / 系统 继承来的环境变量
推论(最容易踩):export ANTHROPIC_MODEL=xxx 再启动 claude 不生效,因为
settings.json 的 env 块会覆盖它。所以:
- 单次切换 → 用命令行参数:
claude --effort high --model deepseek-flash[1m] -p "..." - 会话内即时切换 → 交互模式里用
/effort、/model斜杠命令 - 持久切换 → 改 settings.json(建议写个小工具,见下方 ccmode 思路)
- 千万不要顺手同步一份到 HKCU 环境变量——见 Step 14「单一配置源」
判据校验:
claude --effort bogus -p hi会打印合法值清单,比翻文档快。 实测合法值:low / medium / high / xhigh / max。off不在其中,会被静默忽略。
Step 8 · 用本地中继抓真实请求体(唯一可靠手段)
搭一个 127.0.0.1 上的透明转发,把 ANTHROPIC_BASE_URL 指过去,
就能录到 Claude Code 真实发出的 JSON(含 thinking 配置、工具数、body 大小)。
关键实现点:
- 用
http.server.ThreadingHTTPServer+http.client.HTTPSConnection,纯标准库。 - 上游响应必须边收边发(
transfer-encoding: chunked),否则会破坏 SSE 流。 - 记录
ttfb/first_chunk/total/ 请求体里的thinking/ 响应里的usage。 - 用同目录
tag.txt给每一轮实验打标签,避免多次运行串味。 ANTHROPIC_BASE_URL支持http://,指向 127.0.0.1 时记得把NO_PROXY加上127.0.0.1。
⚠️ 最大坑:在 Bash 工具里用 nohup ... & 起的中继会随该次命令的进程组一起被杀,
表现为「Claude Code 连不上 → 一直重试 → 看起来像卡死」,
而且因为 SIGTERM 打断管道,连报错都看不到。
必须用工具自带的后台运行能力(run_in_background)启动长驻进程。
改坏 settings.json 后要立刻还原,别让它停在指向死端口的状态。
Step 9 · CLAUDE_CODE_EFFORT_LEVEL 对第三方模型通常是空操作
实测(DeepSeek,2026-09 复核):在 low / medium / high / xhigh / max 五档下, Claude Code 发出的请求体完全一致:
"thinking": {"type": "adaptive", "display": "omitted"}
body_bytes 五档完全相同(66008)。因为 Claude Code 判定该模型走
adaptive thinking(模型自己决定想多久,不设 token 预算),
所以根本没有 effort 这个旋钮可拧。
跑出来的对照数据(同一道逻辑题,重复 3 次):
| effort | wall 均值 | 输出 token 均值 |
|---|---|---|
| high | 15.3s | 829 |
| max | 15.0s | 830 |
差异 0.3s / 1 个 token,纯噪声。 结论:对 DeepSeek 别在 effort 上调优,
它不改变任何东西。(low 更快的前提是模型真的收到小预算;adaptive 下不成立。)
判断某模型是否 adaptive:R 代码里 CCn({runtimeOverride, resolvedModel, canonicalModel})==="adaptive"
就读 ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES 里的能力声明。
Step 10 · 把 wall time 拆成「API 耗时」和「Claude Code 开销」
有了中继记录(total = 纯 API 耗时)和 claude -p 的 wall time,一减就出来了:
Claude Code 开销 = wall_s − 中继记录的 total
实测样例(本机):
| 项 | 数值 |
|---|---|
| 中继测得的纯 API 耗时 | 2.9–5.6s(164–221 tok/s) |
| 裸 curl 直连同一道题 | 3.1s(181 tok/s) |
claude -p wall time | 13.4–17.8s |
claude --version(零模型调用) | 4.9–5.5s |
→ API 侧完全正常,瓶颈是 Claude Code 每次进程启动约 5 秒。
反过来说,如果 claude --version 都要好几秒,那「换模型/调 effort」全都白费。
启动慢的常见原因与验证:
for i in 1 2 3; do S=$(date +%s.%N); claude --version >/dev/null 2>&1; E=$(date +%s.%N); \
python -c "print(f'{$E-$S:.2f}s')"; done # 走 npm shim
EXE=<npm>/node_modules/@anthropic-ai/claude-code/bin/claude.exe
$EXE --version # 直接调二进制 —— 关键对照!
cat <claude.exe> > /dev/null # 纯磁盘读 227MB 要多久
echo 'exit 0' > /tmp/n.sh; bash /tmp/n.sh # 空 sh 脚本 —— 量 shell 层开销
⚠️ 先量 shim 层,再怪杀软(2026-09-23 实测推翻了旧结论)
旧结论(错误):「node -e "" 也要 2s → 杀软实时扫描在拖后腿,加 Defender 排除项」。
实测打脸:加了排除项(路径 + 进程)后毫无变化,而真正的差异在别处:
| 路径 | 耗时 |
|---|---|
claude.exe --version(直接调二进制) | 1.14–1.34s |
claude --version(经 npm 的 shim) | 4.06–5.66s |
| 空 sh 脚本(什么都不做) | 1.10–1.41s |
| 读 227MB 二进制 | 1.41s(161 MB/s,磁盘正常) |
→ 多出来的 3–4 秒是「多一层 shell 包装」的开销(claude 实际是
npm/claude 这个 #!/bin/sh 脚本,exec 到真正的 exe;在 MSYS 等 POSIX 兼容层下每层 sh
启动约 1.2s)。不是 Defender,不是磁盘,不是网络。
判断方法:bash /tmp/空脚本.sh 就要 1.2s 的话,说明是当前执行环境的进程创建开销,
用户在自己真实终端里不会有这个损耗 —— 别拿受限环境里的 wall time 当用户的真实体验。
node -e "" 慢不等于杀软:claude 是 native 二进制,根本不经 node 启动,
用 node 当对照组本身就是错的对照。
⚠️⚠️ 性能测量必须 A/B/A,本机噪声能吃掉一切结论
2026-09-23 的惨痛教训:先入为主地认为「慢 = 杀软」,加了一堆排除项, 最后 A/B/A 一测发现全部是噪声。具体数据:
| 项目 | ①无排除 | ②有排除 | ③撤销后 |
|---|---|---|---|
| 建 100 个文件 | 1391ms | 1432ms | 660ms(最快!) |
| 建 60 个目录 | 652ms | 464ms | 761ms(最慢) |
| python 启动(同一状态连测 3 轮) | 790 / 730 / 1303 ms |
同一状态下 python 启动能在 335–1303ms 间波动(4 倍!), 而排除项带来的差异只有几十毫秒 —— 完全淹没在噪声里。
必守规则:
- 任何性能改动都要 A/B/A:改前 → 改后 → 撤销后再测。 只做 A→B 会得出错误结论(顺序效应 = 缓存预热/系统负载)。
- 每项至少重复 10–15 次取中位数,并看标准差。 差异小于 1 个标准差 = 不可信,直接判「无效果」。
- 别拿单轮数据下结论。第一次跑通常偏慢(冷),后面才稳定。
- 大目录
du -sh会超时被 SIGTERM,用 Pythonos.walk加时间上限。 - 单次超过 ~100s 的基准脚本会被前台超时杀掉,拆小或后台跑。
最终结论:Defender 排除项在这台机器上无可测量收益,代价却是 若干目录脱离实时扫描 → 不加。 只有在「单个操作涉及成千上万小文件」(npm install / git clone / 解压大包) 且实测收益稳定 >30% 时,才值得针对那个具体目录临时加。
Defender 排除项若要加(需管理员 + 必须先问用户):
Add-MpPreference -ExclusionPath "<npm>\node_modules\@anthropic-ai\claude-code"
(读排除项也要管理员:HKLM ...\Windows Defender\Exclusions\Paths 普通权限 PermissionError)
加完必须复测;无改善就撤销(Remove-MpPreference),别留着白降防护。
Step 11 · 缓存:默认是好的,别误判
会话内上下文缓存是生效的。同一 session 的第 2 个请求:
cache_read_input_tokens: 16384,input_tokens 从 16359 掉到 174。
别被假象骗了:每次 claude -p 都是全新会话(冷缓存),
单个请求的 cache_read 恒为 0 —— 这不代表缓存坏了。
要验证缓存,必须让一次会话发出 ≥2 个请求(例如给它一个需要调用工具的提示)。
Step 12 · 交互模式「感觉卡住」大多是思考被隐藏了
display: "omitted" 时思考过程不渲染,用户盯着空白等 = 主观上「好慢」。
交互模式下让思考可见的设置键是 showThinkingSummaries: true
(源码:showThinkingSummaries ?? false → 为真则 display: "summarized")。
合法 display 值:summarized / omitted / highlights。
Step 13 · 换大模型前先量一下,pro 有可能更慢
同一道题的裸 API 对照(DeepSeek):
| 模型 | 简单推理 | 多步推理 | 吞吐 |
|---|---|---|---|
deepseek-flash | 2.7–3.5s ✅ | 4.6–10.6s ✅ | 164–204 tok/s |
deepseek-v4-pro | 24.9–32.9s ✅ | 67.6–74.0s ⚠️ | 41–52 tok/s |
- pro 吞吐只有 flash 的 约 1/4;同样一道简单题它也要「想」1300–1565 token(flash 的 3 倍)。
- pro 在多步推理题上会一路想到 max_tokens 上限仍不给结论 —— 提示词里要求「最后一行输出结论」 时它会直接截断。
- 所以:「换个更强的模型」在第三方端点上经常是先换来 4–10 倍的等待。 要换就明确告诉用户这个代价,别默认 pro 更好。
性能问题速查表
| 现象 | 先查什么 |
|---|---|
| 每次启动都慢 | claude --version 计时;杀软实时扫描;二进制大小 |
claude -p 慢但交互不慢 | 每次调用都要付一次进程启动成本,用会话复用/--continue |
| 第一个字出来很慢 | 中继的 ttfb vs first_chunk;adaptive thinking 在想 |
| 每轮都慢 | 中继看 total;对比裸 curl 同题 |
| 换 pro 后更慢 | 正常,见 Step 13 |
| 调 effort 没变化 | 正常,见 Step 9 |
第三部分:收尾——只留一份配置源
Step 14 · 单一配置源(Single Source of Truth)
结论:配置只写在 ~/.claude/settings.json,不要同时在 Windows 环境变量里放一份。
理由(实测):
- 环境变量那份根本不起作用。
settings.json的env块优先级更高(Step 5), 两处同值时行为一致,两处不同值时以settings.json为准。 - 它是麻烦的源头。一旦
settings.json被删、或CLAUDE_CONFIG_DIR变了, 环境变量那份会静默接管并指向另一个模型(可能更贵)。 - 环境变量会泄漏给所有子进程。
ANTHROPIC_AUTH_TOKEN进了系统环境, 任何 npm postinstall、构建脚本都能读到你的 API Key。settings.json只有 CC 自己读。 - 排查时要两处对照,纯粹增加心智负担。
清理流程(清理前先确认没有别的工具依赖这些变量):
import winreg, json, os, ctypes
# 1) 先备份
k = winreg.OpenKey(winreg.HKEY_CURRENT_USER, r'Environment', 0, winreg.KEY_QUERY_VALUE)
hits = {winreg.EnumValue(k,i)[0]: winreg.EnumValue(k,i)[1]
for i in range(winreg.QueryInfoKey(k)[1])
if 'ANTHROPIC' in winreg.EnumValue(k,i)[0].upper()
or 'CLAUDE_CODE' in winreg.EnumValue(k,i)[0].upper()}
json.dump(hits, open(backup_path,'w',encoding='utf-8'), indent=2)
# 2) 删除
k = winreg.OpenKey(winreg.HKEY_CURRENT_USER, r'Environment', 0, winreg.KEY_SET_VALUE)
for name in hits: winreg.DeleteValue(k, name)
# 3) 广播,否则已开的终端仍持有旧值
ctypes.windll.user32.SendMessageTimeoutW(0xFFFF, 0x1A, 0,
ctypes.c_wchar_p('Environment'), 0x0002, 5000, ctypes.byref(ctypes.c_ulong()))
清理前必查:有没有别的消费者(aider / codex / 自己写的 curl 脚本 / MCP 配置里的
${ANTHROPIC_*})。查法:在用户目录里 grep ANTHROPIC_AUTH_TOKEN|ANTHROPIC_BASE_URL。
⚠️ grep 坑:WorkBuddy 工作区里若有名为
nul的文件,ripgrep 会直接os error 1崩掉退出码 2;大目录还会 30s 超时。改用 Pythonos.walk自己过滤后缀和跳过大目录。
验证删干净了没有(关键:必须在干净环境里跑,否则当前 shell 还继承着旧值):
import os, subprocess, re
env = {k:v for k,v in os.environ.items()
if not (k.upper().startswith("ANTHROPIC") or k.upper().startswith("CLAUDE_CODE"))}
p = subprocess.run([r"C:/Users/<u>/AppData/Roaming/npm/claude.cmd",
"-p", "hi", "--output-format", "json"],
capture_output=True, text=True, env=env, timeout=240,
stdin=subprocess.DEVNULL)
print(re.search(r'"canonicalModel"\s*:\s*"([^"]*)"', p.stdout).group(1))
能正常返回 canonicalModel 就证明 settings.json 单独撑得住。
subprocess 坑:Windows 上传
"claude"会FileNotFoundError,必须给claude.cmd的完整路径。
配套要求:如果你写了自己的切档工具,它必须只写 settings.json。 否则下次切档又把环境变量写回来,两份配置死灰复燃。
第四部分:Windows 环境注意点
ConnectionResetError: [WinError 10054] 满屏 traceback(2026-10-06 实测根治)
症状:网关窗口刷出整块 traceback,源头是 socketserver.py 的
process_request_thread,栈底是 handle_one_request → rfile.readline →
socket.recv_into:
Exception occurred during processing of request from ('127.0.0.1', 10511)
File "socketserver.py", line 766, in __init__ ... self.handle()
File "http\server.py", line 415, in handle_one_request
ConnectionResetError: [WinError 10054] 远程主机强迫关闭了一个现有的连接。
这本身不是故障 —— 客户端中途放弃请求就会这样。但必须处理,因为:
- 一次中断刷一整块 traceback,几十行起步;
- 它会把真正该看的日志(上游 400/5xx、
UNEXPECTED ERROR)淹没; - 看起来像网关崩了,实际连接是好的。
常见触发(都是正常流量,不是 bug):用户按 Esc / Ctrl+C 取消、 Claude Code 换掉不再需要的请求、keep-alive 空闲 socket 被对端回收、 流式响应读到一半客户端就关窗。
修法(ccproxy.py,两处 + 一个常量):
CLIENT_GONE = (ConnectionResetError, ConnectionAbortedError, BrokenPipeError)
Handler.handle_one_request覆盖:包住基类调用,只捕获上面三个异常 → 置close_connection = True,打一行说明后正常返回。- 新增
QuietThreadingHTTPServer(ThreadingHTTPServer),覆写handle_error:CLIENT_GONE→ 一行日志(路由到log(),可被 verbose 关闭)TimeoutError→ 一行日志(空闲 keep-alive 被回收也是这个形态)- 其他异常 →
log_always()打出UNEXPECTED ERROR handling request from ...再调super().handle_error()保留原traceback。 绝不能静默吞掉真故障。
main()里改用srv = QuietThreadingHTTPServer(...)。- 新增
log_always():不受--verbose影响的输出通道。 桌面启动器默认不加--verbose,真实错误若走log()就永远看不见 —— 这是排查问题时最容易踩的空。
WinError 10053(本地软件中止了已建立的连接,中文系统上对应 ECONNABORTED)
与 10054 同类,也要一并捕获;流式写回时它已被 do_POST 的 except 收尾。
验证方法:不能只测正常请求,要主动制造中断:
# 1) 发一半 body 就 close
s.sendall(headers + body[:len(body)//2]); s.close()
# 2) 连上就 close,一个字节都不发
s.close()
# 3) 流式响应读一半就 close
r.read(120); c.close()
每种打 3 次,然后检查网关 stderr:零 traceback,且每个请求恰好一行日志。 实测 9 次中断 → 9 行简洁日志,功能回归(keep-alive 10/10、中断场景 4/4)全通过。
stream error 10054 之后再无请求 → 会话静默卡死(2026-10-06 实测根治)
症状(与上一节的 traceback 刷屏完全不同,别混淆):
[ccproxy] stream error: [WinError 10054] 远程主机强迫关闭了一个现有的连接。
[ccproxy] client disconnected before the response was sent (harmless - it cancelled the request)
[ccproxy] "GET /health HTTP/1.1" 200 -
<此后日志静默,客户端再也没有新请求发出>
/health 还能 200,说明监听线程活着;但真实推理请求一个都不再出现,
整个会话像卡死。这不是客户端问题,是网关的 bug。
根因(两条独立缺陷,缺一不可):
- 非流式路径的
resp.read()会永久阻塞。上游先回Content-Length: N再发 RST(SO_LINGER{1,0}),http.client会一直等 满 N 字节,RST 只让recv抛一次、被重试后继续等 → 线程永久卡住, 客户端既收不到响应也等不到连接关闭(实测http=000,6/6 全挂)。 - 流式路径用「假装成功」掩盖截断。RST 后旧代码调
tr.finish(), 照发message_delta(end_turn)+message_stop。客户端看到的是 一个语法完全合法、内容却被截断的"完整"回答,于是接受它、不重试、 不再发新请求 —— 表现就是「然后就没有新请求被发出来了」。
为什么"重启就好"骗人:ThreadingHTTPServer 每请求一线程,卡死的线程
不会传染,流式请求仍能 200(实测 RST 后 stream 200 / health 200,
只有 stream:false 挂死)。所以看起来"时好时坏",实则取决于
Claude Code 该轮是否发了非流式请求。
修法(ccproxy.py 三处):
def do_POST(self):
self._responded = False # ① 区分"还没回复"和"已回复"
...
if not want_stream:
try:
raw_body = resp.read()
except Exception as e:
log_always("upstream body read failed mid-flight: %s: %s" % (...))
self._send_error_anthropic(502, "api_error",
"upstream response was truncated: %s" % e)
return # ② 绝不静默挂死
...
except Exception as e:
log_always("stream error: %s: %s" % (type(e).__name__, e))
if want_stream:
self._send_stream_error("api_error", ...) # ③ error 事件,不补 message_stop
elif not self._responded:
self._send_error_anthropic(502, "api_error", ...)
finally:
self.close_connection = True # 不留半开 keep-alive
③ 是关键:流式失败必须发 event: error(Anthropic 规范里表示
"这次尝试失败"),不能补 message_stop。补了等于告诉客户端
"这条回答完整结束了",客户端就不会重试。
验证方法(必须造 RST,不能只测正常请求):
写一个假上游,SO_LINGER{1,0} 后 close() 制造真 RST:
self.connection.setsockopt(socket.SOL_SOCKET, socket.SO_LINGER, struct.pack("ii", 1, 0))
self.connection.close()
非流式要谎报 Content-Length(len(body)+50 但只发 len(body))
才能复现永久阻塞。修复前:6/6 http=000 挂死;修复后:6/6 在 44ms 内
返回 502,流式路径发出 event: error 且带已输出字符数。
排查这条坑时踩到的两个环境陷阱(都不是代码问题,别误判成 bug):
nohup ... &启动的进程会随工具 shell 退出被回收。日志停在最后一行、 端口无监听、/health返回 502 —— 看起来像"网关又挂了"。 工具里必须用后台任务方式启动(run_in_background)才活得久。上游。实测无 UA / 浏览器 UA / 诚实 UA 各 3 次全部干净收尾(9/9),不要在这上面浪费时间。 ⚠️ 2026-10-07 更正:这条只在直连时成立。经代理出口时 UA 恰恰是致命项 —— 见下节「Cloudflare 1010」,当时正是这条旧结论让人差点改错方向。User-Agent不是断流原因
请求行带绝对 URL → 404(2026-10-07 实测根治)
症状:网关日志里请求行长这样,混在正常请求中间:
[ccproxy] "POST /v1/messages?beta=true HTTP/1.1" 200 -
[ccproxy] "POST http://127.0.0.1:3457/v1/messages?beta=true HTTP/1.1" 404 -
[ccproxy] "POST http://127.0.0.1:3457/v1/messages?beta=true HTTP/1.1" 404 -
Claude Code 侧表现为跑到一半报:
There's an issue with the selected model (space-bunny[1m]). It may not exist or you may not have access to it. Run --model to pick a different model.
—— 这句提示极具误导性:模型明明是好的,上下文窗口也确实是 1M。
根因:经代理(PROXY / TUN)时,客户端发给代理的是绝对形式的请求目标
(RFC 7230 §5.3.2 允许代理把绝对 URI 发给下一跳)。网关原来用
self.path.split("?")[0] 取路径,于是得到
http://127.0.0.1:3457/v1/messages —— 带 scheme 和 host,
跟 /v1/messages 比对不上 → 404。
修法(两处,do_POST 与 do_GET 各一个):
from urllib.parse import urlparse # 确认已导入
# do_POST
path = urlparse(self.path).path # 原:self.path.split("?")[0]
# do_GET
if urlparse(self.path).path in ("/health", "/", "/status"):
urlparse().path 对两种形式都只返回路径部分,是标准解法。
验证(用裸 socket 发绝对 URL,别只测相对路径):
s = socket.create_connection(("127.0.0.1", 3457), timeout=60)
req = (b"POST http://127.0.0.1:3457/v1/messages?beta=true HTTP/1.1\r\n"
b"Host: 127.0.0.1:3457\r\nx-api-key: " + tok.encode() +
b"\r\ncontent-type: application/json\r\nContent-Length: " +
str(len(body)).encode() + b"\r\nConnection: close\r\n\r\n" + body)
实测修复后:相对路径 200、绝对 URL 200、绝对 URL 的 count_tokens 200,
真实 claude.exe -p 带 Bash 工具跑 6 轮 is_error=false。
判据:日志里同时出现 /path 和 http://host/path 两种形式 → 就是这个坑。
http.client 不会把绝对 URL 发给你,所以这类问题只在本机直连的测试里复现不出来,
必须真的经代理跑一次多轮工具调用才会暴露。
error code: 1010:User-Agent 被 Cloudflare WAF 拦(2026-10-07 实测根治)
症状:网关窗口刷 502 / WinError 10054,failures jsonl 里清一色
upstream_status 599 + ConnectionResetError,看起来像"上游挂了/网络不通"。
但模型其实好好挂着,配置一个字都没错。
根因:ccproxy.py 原来只发 Content-Type + Accept,不发 User-Agent。
Python 客户端栈(urllib.request 会自动加 Python-urllib/3.x;裸 http.client 则可能干脆不发)被 Cloudflare 的 WAF 识别成机器人 →
回 403 error code: 1010。且仅在经代理出口 IP 时触发,直连不触发。
决定性 A/B 表(各2 次,6/6 稳定复现):
| 链路 | User-Agent | 结果 |
|---|---|---|
| 经代理 | Python 默认(不设) | 403 error code: 1010 |
| 经代理 | ccproxy/1.0 (+local gateway) | 200, 1.9s |
| 经代理 | 浏览器 UA | 200, 1.6s |
| 直连 | Python 默认 | 200 ✅ |
| 直连 | 诚实 UA | 200, 2.0s |
修法(ccproxy.py 的 _open_upstream(),一行):
headers = {
"Content-Type": "application/json",
"Accept": "text/event-stream" if oa_req.get("stream") else "application/json",
# 不设 UA 会被 WAF 403 1010,且表象像"上游挂了"
"User-Agent": "ccproxy/1.0 (+local gateway)",
}
诚实 UA 就够,不必伪装浏览器。顺带:直连时带 UA 反而快 6 倍 (12.5s → 2.0s,慢的那次是 WAF 排队)。
⚠️ 判据顺序:403/4xx 错误码 > 超时
这才是本次最贵的教训:第一轮我看到 http=000 / 15s 超时 / WinError 10054
就断定"Zen 上游对本机不可达",还据此建议改网关的代理策略 —— 方向完全错了。
超时是最不可靠的信号,因为它能由"拒绝"伪装出来(WAF 断连 / RST / 静默丢弃)。
→ 见到超时应先设法拿到一个状态码(直连绕过代理打一次、看 failures 里有没有
upstream_status、或换 curl -v 看 TLS 握手在哪一步断)。
upstream_status 599 是网关自己的合成码,不是上游返回的真实码 ——
它只说明"连接没能完成",不能推出"上游不可用"。
真实错误码出现了(403 / 401 / 400)才是有信息量的。
为什么模型清单能 200 而推理 403
GET /zen/v1/models 是公开只读端点,WAF 放行;POST /zen/v1/chat/completions
才走 WAF 规则。所以"能拉到模型清单"不能证明"推理能通" ——
别用它当健康判据(/health 只验网关自己,不打上游,同样不能证明上游可用)。
教训:log_always 打出的 stream error 不是"无害噪音",它是
上游链路已经断了的唯一信号。下一条请求不来时,先查
netstat -ano | findstr :3457 看监听是否还在 —— 监听在但请求不来,
才是本节这个 bug。
别把工具的进程回收当成崩溃:用工具后台任务启动的长驻服务,会在
任务生命周期结束时收到 status: failed 通知,但那是外壳被回收,
不等于进程死了。以 netstat + /health 为准 —— 实测出现过
通知报 failed、PID 已从 12040 变成 2400(被重新拉起)、端口仍在监听、
流式与非流式请求依然 200 的情况。判定标准只有一个:端口是否 LISTENING。
判据:看到 socketserver 的 traceback 先别查网关逻辑 ——
先确认异常类型。CLIENT_GONE / TimeoutError 是客户端行为,与网关无关;
其它类型才顺着 log_always 标记去查。
count_tokens 404 连环污染:Bad request syntax ('{"model"... (2026-10-06 实测根治)
症状(日志里连着出现,顺序固定):
"POST /v1/messages?beta=true" 200 -
"POST /v1/messages/count_tokens?beta=true" 404 -
code 400, message Bad request syntax ('{"model":"space-bunny","messages":[...}],"tools":[]}POST /v1/messages?beta=true HTTP/1.1')
"POST /v1/messages?beta=true" 200 -
那个 code 400 ... Bad request syntax 不是上游报错,是 BaseHTTPRequestHandler
自己打出来的 —— 注意它在消息里重复了整个请求体并紧跟下一条请求行,这是决定性特征。
看起来像客户端发了畸形请求、或像 body 里带了奇怪字符,实际都不是。
根因(两个叠加):
- 缺
/v1/messages/count_tokens端点。Claude Code 每次请求前都调它算上下文预算, 而do_POST只认/v1/messages,其它路径直接 404。 - 致命的那一半:404 是在读取请求体之前返回的。HTTP/1.1 keep-alive 下,
客户端已经把几十 KB 的 body 写进 socket 了,我们没读走 →
下一个请求复用同一 socket 时,解析器从残留 body 中间开始读 →
把 body 的 JSON 当成请求行 →
Bad request syntax。 body 越大越容易触发(本例 body 是整个 page.tsx)。
→ 判据:BaseHTTPRequestHandler 里任何 return 之前,都必须先把 body 读干净。
修法(ccproxy.py,两处):
- 新增
_drain_request_body():按 64KB 分块读干净Content-Length, 再处理 chunked(de-chunk 到结束块并吃掉其后的 CRLF), 返回 body 字节(供后续复用,别读第二次)。 do_POST第一行就raw = self._drain_request_body(), 然后 404 / 401 / bad json 等所有早退分支都在 body 已读走之后才返回。- 实现
/v1/messages/count_tokens:本地估算即可(复用estimate_tokens的字符数/3.5),返回{"input_tokens": N}。它本来就只是给 auto-compact 做阈值比较,不需要真 tokenizer。别再 404 —— 404 本身就是 bug 的来源。 - 401 分支也要排空:未授权请求同样带 body。
三个连带坑:
_drain_request_body必须返回 body。若它丢弃,调用方还得再读一次self.rfile.read()→ 拿到空 →_count_tokens恒返回 0。- 分块读取要用
min(remaining, 65536)循环,别一次read(n); 大 body(实测 300KB)容易短读。 - chunked 传输要读到 size=0 的结束块并吃掉其后的 CRLF,否则边界仍不对齐。
验证方法(必须测 keep-alive,不能只测单请求):
用一个 http.client.HTTPConnection 复用同一连接,先打 count_tokens,
再在同一连接上打 /v1/messages,第二次必须是 200。
实测覆盖:count_tokens→messages 同连接 200;未知路径 404→messages 同连接 200;
同一连接交替 10 次 10/10 全 200;401 路径后同连接 200;300KB body 200 且
message_stop 恰好 1 次;真实 claude.exe 多轮全 200。
顺带说明:日志里
401出现在 count_tokens 上是正常的 —— 那是本节测试 故意不带 token 打的,目的是确认 401 路径也不会污染连接。
间歇性 upstream 400 invalid request:tool_result 前插了 user 消息(2026-10-06 实测根治)
症状:用 ccproxy + Space Bunny 时,会话中途间歇性 400,日志只有一句
upstream 400 {"error":{"type":"invalid_request_error","message":"... [invalid_request_error] invalid request"}},
完全不说哪条消息有问题。有的请求 200、下一条就 400,CC 会自动重试所以有时能过去,
表现为"卡一下"。看起来像限流、像内容太长、像模型名错,都不是。
根因:Claude Code 会在 assistant 的 tool_use 和它的 tool_result 之间
插入 user 消息(AskUserQuestion 的回答、hook 输出、中断式输入)。转成 OpenAI 格式后
就变成:
assistant(tool_calls) -> user -> tool ← tool 脱离了它的 assistant
严格的 OpenAI 兼容网关拒绝这个形状。实测确认:
M[:38](结尾是 user)→ 200M[:39](结尾是 tool)→ 400- 把那条 tool 的
content换成完全合法的 user 消息 → 200 - 连
tool_call_id是假值的孤儿 tool 消息 → 400 max_tokens从 32000 降到 2048 → 仍 400(排除 token 预算)
→ 判据:tool 消息前面紧邻的必须是声明它的那个 assistant(含 tool_calls), 中间不能夹 user/system。
修法(ccproxy.py 的 _repair_message_sequence,已内置):把夹在
assistant 与其 tool 结果之间的 user/system 消息移到 tool 结果之后,
并把它们的文本前置合并进第一个 tool 结果的 content —— 不丢任何信息。
函数返回新列表,单趟扫描,幂等,不修改入参。
排查这类"上游说 valid 但没说是哪个"的 400 的通用手法
- 先抓真实请求体:网关在 upstream != 200 时把
oa_req落到~/.claude-code-proxy-failures.jsonl(含 summary + 完整 body,>256KB 自动截断)。 设为CCPROXY_DUMP_FAILED=0可关闭。没有这步就只能猜。 - 前缀扫描找临界点:
for k in range(30,41): post(M[:k])—— 精确定位 「加哪一条开始 400」。本例first 38 -> 200 / first 39 -> 400,一步锁定。 - 对照实验排除干扰:同一条消息换 role / 换 content / 改 max_tokens / 删一半, 看 400 是否消失。别只试一个变量。
- 别被"1 个字符也 400"误导:单独发一条
{"role":"system","content":"x"}也 400, 看起来像"system 消息不被支持",其实是该消息后面没有 user。 → 任何"最小用例也失败"都要怀疑结构约束,不要怀疑内容。
修完必须做的回归
- 离线单测 13 个用例覆盖:正常配对、单/多 user 插入、user+system 插入、
多 tool 中途插入、连续 3 次插入、空 tool content、幂等性、入参不被修改。
断言三件事:无
user/system -> tool相邻、无内容丢失、无孤儿tool_call_id。 - 用抓到的真实失败 body 回放 → 必须 200。
- 真实
claude.exe -p多轮带工具 → 失败日志必须为空。
Windows .cmd 启动器:编码与换行是头号坑(2026-10-05 实测)
给用户写 Windows 批处理启动器,必须 GBK 编码 + CRLF 换行,否则整段脚本会被 cmd.exe 拆成碎片:
| 症状 | 根因 |
|---|---|
'nny' is not recognized... | 文件是 UTF-8 + LF,cmd.exe 把 Bunny 之类行截断(LF 不算行尾) |
'--verbose' is not recognized... | 同上,某行被拆成独立命令行 |
'任意键关闭窗口。' is not... | 同上 + GBK 解码 UTF-8 产生乱码 |
The system cannot find the path specified. | 上一行的乱码把路径写坏了 |
正确写法:用 Python 显式控制编码,别用 Write 工具直接写(默认 UTF-8 + LF):
open(path, "wb").write(("\r\n".join(lines) + "\r\n").encode("gbk"))
中文提示语配合 chcp 936;若必须 UTF-8 中文,则 chcp 65001 且文件存 UTF-8 + CRLF。
中文文件名本身没问题,坏的是内容编码。
批处理里三个必须避开的坑
timeout会被 Git Bash / MSYS 的 coreutils 抢占 → 报timeout: invalid time interval '/t'。延时改用ping -n 2 127.0.0.1 >nul。- 用了
!VAR!就必须setlocal EnableDelayedExpansion,否则取到空值, 清理/条件分支静默失效(if defined OLD那套同理)。 for /f取 netstat 的 PID:netstat -ano | findstr LISTENING | findstr ":PORT "取第 5 个 token;注意排除TIME_WAIT(它不是 LISTENING)。
端口占用的静默卡死
端口已被另一个网关实例占用时,ccproxy.py 不会报错退出,而是继续挂着,
表现为「双击启动器 → 窗口有输出 → 但 claude 连不上」。启动器必须先清理:
for /f "tokens=5" %%P in ('netstat -ano ^| findstr LISTENING ^| findstr ":3457 "') do set "OLD=%%P"
if defined OLD taskkill /F /PID !OLD!
# kill 后必须复检一次,仍占用则报错退出,别让用户干等
ccswitch.py 自带的网关拉起有同样问题(见上「本机坑」表)。
验证启动器时务必先手动清空端口,否则测的是「旧实例还活着」,
会误判成新启动器正常。
其它本机坑
| 现象 | 说明 |
|---|---|
subprocess.run(["claude", ...]) → FileNotFoundError | Windows 上必须给 claude.cmd 的完整路径 |
| ripgrep/Grep 工具全目录搜索失败 | 工作区里若有名为 nul 的文件会 os error 1(退出码 2);大目录 30s 超时。改用 Python os.walk 过滤后缀 |
| 需要跑管理员权限的命令 | 用标准的 UAC 提权方式(Start-Process -Verb RunAs 或 ShellExecuteEx+runas),执行前先向用户说明并征得同意 |
附录 A · 智谱 GLM 已知可用配置(2026-09 实测)
智谱官方原生支持 Anthropic 协议,文档里直接给了 Claude Code 配置,接入最省心。
端点与模型名(权威,无需猜)
- Anthropic 协议 Base URL(Claude Code 用这个):
https://open.bigmodel.cn/api/anthropic- ⚠️ 末尾不要加
/v1——Claude Code 会自动拼/v1/messages,拼成https://open.bigmodel.cn/api/anthropic/v1/messages(这正是智谱的正确路径)。 - 国际站 z.ai 同协议:
https://api.z.ai/api/anthropic(Key 用 z.ai 平台发的)。
- ⚠️ 末尾不要加
- API Key:
https://open.bigmodel.cn/usercenter/apikeys创建。 填进ANTHROPIC_AUTH_TOKEN(即 Key 本身,CC 会带x-api-key头,别加Bearer)。 - 模型 ID(小写,OpenAI/Anthropic 端点通用):
- 免费视觉:
glm-4.6v-flash(128K,9B 轻量,免费档仅 1 并发) - 免费文本:
glm-4.7-flash/glm-4.5-flash - 便宜强档:
glm-5.3-flash(1M 上下文,约 ¥1.07/¥3.55)、glm-5.2 - 旗舰:
glm-5
- 免费视觉:
配置模板(settings.json 的 env 块)
{
"env": {
"ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
"ANTHROPIC_AUTH_TOKEN": "你的智谱API Key",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flash",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.3-flash[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.3-flash[1m]",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
"API_TIMEOUT_MS": "600000"
}
}
GLM 接 CC 的三个坑
glm-4.6v-flash免费档只有 1 并发请求(ayautomate 实测)。Claude Code 会并行发 子代理/工具调用请求,极易触发限流排队 → 实际体验卡顿。当主模型不推荐,更适合走 「视觉理解 MCP Server」(glm-4.6v) 或 lobehub 的glm-4.6v-flash-mcp只处理图片/视频任务。- 上下文 128K 的模型别加
[1m]后缀(如glm-4.6v-flash就别加)。[1m]只给真有 1M 窗口的模型用(如glm-5.3-flash[1m]),否则contextWindow会虚标导致 auto-compact 错乱。 - 免费模型商用条款未明确(ayautomate 标注 "Commercial use: Unclear")。个人使用无妨;
要进生产先查智谱当前条款。复杂编码优先用
glm-5.3-flash或glm-4.7-flash(免费文本), 比视觉 Flash 更能扛多步任务。
第五部分:只有 OpenAI 兼容端点的模型 → 必须加本地网关
适用:模型只在 OpenAI 兼容网关上提供,没有 Anthropic 原生端点。 典型是 OpenCode Zen 的免费层(2026-09 时是 Space Bunny,1M 上下文、强制推理、五档 effort、$0)。
✅ 2026-10-16 更正:
space-bunny-free并未下线,实测可用且很快。 早前记为「已下线」是错的。13:28 经zen_bridge(:8787) 与 ccproxy(:3463) 两段实测: 对话正常、工具调用命中get_weather、端到端 13.5s。现役 profile 为zen-ds-flash(deepseek-v4.1-flash-free)。Zen 免费层不能直连:直连报
FreeTierError: only used from within OpenCode(改 UA 伪装无效),必须走opencode serve+ 本地桥接,见第八部分。免费模型已全部接进切换器(
~/.claude/profiles/+claude_model_switcher.pyw的MODELS/DEL_LABELS已登记;6 个也已进~/.workbuddy/models.json):
profile 模型 ccproxy 端口 真实上下文 端到端 zen-longcatlongcat-2.5-preview-free3465 1M 4.2s zen-mimomimo-v2.6-flash-free3467 200k 4.9s zen-nemotron-vlnemotron-3.5-super-vl-free3464 1M 6.9s zen-big-picklebig-pickle3468 200k 12.1s zen-space-bunny👑space-bunny-free3463 1M 1.3s zen-ll-alphall-alpha-free3469 256k 3.5s zen-ds-flashdeepseek-v4.1-flash-free3462 200k 4.0s 不可用:
jev-1.13-free(500)、cat-jam-free与muse-spark-1.3-contributor-free(200 但空 content= 地区封锁)、muse-spark-1.2-contributor-free(500)。nemotron-3.5-lightning-free能跑但用户决定不接入(端到端偏慢,历史最慢测到 18.6s, 已从 profile / GUI / models.json / KNOWN_FREE 全部移除;端口 3466 因此空出)。踩坑要点:
- 每个模型必须独占一个 ccproxy 端口(不同 upstream 不能共端口)。新增模型时
x_gateway_port与x_ccproxy_args --model要成对改。[1m]后缀只给真实 1M 上下文的模型(表中 1M 那几个)。别照抄——zen-ds-flash标的[1m]其实只有 200k,靠CLAUDE_CODE_AUTO_COMPACT_WINDOW兜底。- GUI 模型清单是硬编码的,只加 profile 文件 GUI 里不显示;
ccswitch.py是动态扫目录。- 桥接不开机自启(2026-10-16 移除 Startup 里的
zen-bridge-autostart.cmd, 原文件备份在~/.claude/backups/zen-bridge-autostart.cmd.removed-*): 改为点切换器时才起。GUI 打开后 400ms 自动连PREFERRED_PROFILE(当前 =zen-space-bunny👑,静默执行不弹框),这条链路顺带把 zen_bridge 和对应 ccproxy 网关都拉起来。冷启动约 30s(含opencode serve)。 改默认模型只需改 GUI 顶部的PREFERRED_PROFILE常量。- 判「可用」不能只看 HTTP 200:地区封锁返回 200 + 空 content。
- 🔴 绝对不要把 Zen 模型配成 WorkBuddy 自定义模型(2026-10-16 实测踩坑): WorkBuddy 发的是完整 agent 提示词 + 25 个工具定义(约 34K 字符), 桥接转给
opencode serve后,opencode 的 general agent 会把提示当任务自己执行—— 用它自己内置的工具去读写用户真实项目文件(实测抓到它跑Get-ChildItem D:\ai-case-library\tmp、read tmp\*.log),形成 agent 循环, WorkBuddy 侧永远停在「准备中」。已从~/.workbuddy/models.json移除全部 Zen 条目。
- 本文件桥接源码注释其实已预警:「system 会被 opencode agent 自己的提示压掉, 模型会转头去用它内置的工具」——WorkBuddy 的提示词体量让这从「可能」变「必然」。
POST /session/:id/abort对正在跑的 subagent 循环无效(返回 200 但仍在更新), 唯一可靠手段是杀掉opencode serve进程。- 小提示请求不会触发接管,所以端到端测试全绿也掩盖了它——只有真实 agent 提示词才暴露。
- Claude Code 侧不受影响:请求经 ccproxy,工具集小,实测 1.3~3.5s 正常返回。
- 本机代理
127.0.0.1:9749出口与直连相同(江苏联通),测 VPN 需开 TUN/全局模式。- **上表耗时是单次采样,噪声大,别据此下结论。**以 2 轮基准为准 (真实提示 + 并行工具调用「查北京和上海」):
space-bunny-free1.3s(1.1/1.4) 👑 最快最稳 >nemotron-3.5-super-vl-free1.7s
deepseek-v4.1-flash-free1.9s >big-pickle3.2s >longcat-2.5-preview-free5.6smimo-v2.6-flash-free8.2s(3.7/12.8,很不稳)。6 个都能正确一次返回多个tool_use。 👑 = 实测最优,GUI 已标皇冠,日常首选。 ⚠️ 反面教材:单次采样曾把space-bunny-free测成 13.5s(最慢)、longcat测成 4.2s(第二), 复测后完全颠倒。性能结论必须多轮。本部分剩余内容保留作 OpenAI→Anthropic 网关类问题 的历史排查参考。
⚠️ 2026-09-29 重大更正:
claude-code-router的流式转换是坏的,不要再拿它做方案。 实测 v2.1.1(npm 上只有 2.1.0/2.1.1,没有修复版)输出的 Anthropic SSE: 每个事件都写两遍(两个不同的message_start)、从不发message_stop、message_delta.delta是空{}。Claude Code 因此报API Error: The response stream was malformed. The response above may be incomplete.定位手法(可复用):把它指向一个标准得不能再标准的假上游——自己起个 Python HTTP 服务 返回教科书式 OpenAI SSE(
data: {...}\n\n+finish_reason+data: [DONE])—— 照样畸形,说明是路由器自身 bug,与上游无关;再查假上游的请求日志确认上游只被请求 1 次, 即重复输出是它自己写了两遍。替代方案:自建
ccproxy.py(见第七部分),零依赖、事件序列严格合规。 下面的路由器配置留作历史参考,新搭建请直接走第七部分。
同一个 stealth 模型往往有多个上游,优先选免 key 的那个:
| 上游 | 端点 | 模型名 | 认证 | 状态 |
|---|---|---|---|---|
| OpenCode Zen | https://opencode.ai/zen/v1/chat/completions | deepseek-v4.1-flash-free | 免 key(匿名) | ✅ 现役,但必须走 opencode SDK(见第八部分) |
| OpenCode Zen | 同上 | space-bunny-free | 免 key | ✅ 实测仍可用(2026-10-16,profile zen-space-bunny,端口 3463);早前「已下线」的记录有误 |
| OpenRouter | https://openrouter.ai/api/v1/chat/completions | stealth/space-bunny-alpha | 需 key(注意:整段 :free 后缀会 404) | ❌ 随模型下线 |
| AI/ML API | https://api.aimlapi.com/v1/chat/completions | stealth/space-bunny-alpha | 需 key | ❌ 随模型下线 |
- Zen 免 key 的代价(2026-10-16 实测):Zen 免费层只接受从 opencode 客户端/SDK 发出的
请求。匿名直连 endpoint 会
FreeTierError: only used from within OpenCode, 改User-Agent伪装无效;甚至用 pythonurllib打opencode.ai还会被 Cloudflare403 error code: 1010拦。所以现役方案是opencode serve+ 本地桥接。 - 两条通道 模型 ID 不同:Zen 带
-free后缀,OpenRouter 不带:free后缀。
为什么必须过网关
Claude Code 只发 Anthropic Messages 协议,这类模型只吃 OpenAI Chat Completions。
协议不同,ANTHROPIC_BASE_URL 直接指过去必炸。用 claude-code-router 在本地
做协议转换(含流式 + 工具调用 + 推理参数翻译)。
架构:Claude Code → http://127.0.0.1:3456 → claude-code-router → OpenRouter
⚠️ 最大坑:配置文件名是 config-router.json,不是 config.json
这是「配置明明写了却不生效」的头号原因,静默失败,极难查:
DEFAULT_CONFIG_PATH = path.join(homedir(), ".claude-code-router", "config-router.json")
- README / 网上教程普遍写
config.json—— 错的。 - 写错文件名后路由器不会报错,而是加载内置
DEFAULT_CONFIG, 里面塞着codewhisperer-primary(AWS)和shuaihong-openai两个陌生 provider。 - 识别方法:跑
ccr health,若出现你不认识的 provider 名,就是没读到你的配置。
⚠️⚠️ 同等大坑:系统代理环境变量接管网关请求
网关内部用 axios,而 axios 会读取 http_proxy/https_proxy/HTTP_PROXY/HTTPS_PROXY
环境变量。本机(或任何开了代理的机器)若设了这些变量,网关会把所有上游请求都交给代理转发,
症状极具迷惑性:
| 现象 | 说明 |
|---|---|
打上游得 400,但用 curl 直连同一上游是 200/401 | 代理层引入的假错误 |
打本地 http://127.0.0.1:xxxx 得 502 | 代理无法回环(连 localhost 也被转发) |
| 不同上游表现不一致、模型名明明正确却失败 | 别怀疑模型名,先查代理 |
定位法(决定性):架一个本地回显 HTTP 服务器(Python stdlib),把网关 endpoint 临时
指到 http://127.0.0.1:3999/v1/chat/completions,再经网关发一次请求:
- 回显服务器收到请求 → 网关没有经代理转发(可继续查别的)。
- 回显服务器收不到、网关报 502 → 请求被代理接管了(本地地址也被代理吞掉)。
修复:按 HTTP 客户端通用的 no_proxy 约定,把本地回环地址与直连可达的上游域名列入
no_proxy,即声明这些目标不走代理(其余流量仍按系统代理设置走):
# bash:只为回环地址声明直连,其余保持系统代理设置
NO_PROXY='127.0.0.1,localhost' no_proxy='127.0.0.1,localhost' <node.exe> <cli.js> start
REM Windows 启动器里
set NO_PROXY=127.0.0.1,localhost
set no_proxy=127.0.0.1,localhost
<node.exe> <cli.js> start
若确实需要「这个进程完全不使用任何代理」(例如上游必须直连、而系统代理不通), 再显式覆盖这几个变量——先确认该上游直连可达(不带代理参数
curl能返回 200), 且只对单个进程生效,不要写成全局永久环境变量。
注意:这一条对所有「本地网关转上游」的场景都适用(不只 claude-code-router)。
Claude Code 自己连 127.0.0.1:3456 时同样可能被代理接管 → 在 no_proxy 里加上 127.0.0.1。
安装(装进 managed node workspace,别 npm install -g)
mkdir -p "C:/Users/<u>/.workbuddy/binaries/node/workspace"
cd "C:/Users/<u>/.workbuddy/binaries/node/workspace"
"<node.exe>" "<版本根目录>/node_modules/npm/bin/npm-cli.js" install claude-code-router
npm-cli.js 在版本根目录
.../node/versions/22.22.2-3/node_modules/npm/bin/npm-cli.js, 不在 workspace 里(踩过)。
配置模板:~/.claude-code-router/config-router.json
历史示例(模型名
space-bunny-free已下线,仅作格式参考;新搭建请用第七部分的ccproxy.py+ 第八部分的zen_bridge.py)。
{
"server": { "port": 3456, "host": "127.0.0.1" },
"routing": {
"rules": {
"default": { "provider": "opencode-zen", "model": "space-bunny-free" },
"background": { "provider": "opencode-zen", "model": "space-bunny-free" },
"thinking": { "provider": "opencode-zen", "model": "space-bunny-free" },
"longcontext": { "provider": "opencode-zen", "model": "space-bunny-free" },
"search": { "provider": "opencode-zen", "model": "space-bunny-free" }
},
"defaultProvider": "opencode-zen",
"providers": {
"opencode-zen": {
"type": "openai",
"endpoint": "https://opencode.ai/zen/v1/chat/completions",
"authentication": { "type": "bearer", "credentials": { "apiKey": "" } },
"settings": {
"categoryMappings": { "default": true, "background": true, "thinking": true,
"longcontext": true, "search": true },
"models": ["space-bunny-free"],
"defaultModel": "space-bunny-free"
}
}
}
},
"debug": { "enabled": true, "logLevel": "info", "traceRequests": false,
"saveRequests": false, "logDir": "C:/Users/<u>/.claude-code-router/logs" }
}
要点:
endpoint要写完整/v1/chat/completions路径(不是 base URL)。- 路由器按 category 路由,忽略 Claude Code 请求里带的 model 名,
真正生效的是 rule 里的
model。所以 settings.json 里写space-bunny也无所谓。 - 五个 category 全部指向同一 provider,否则子代理 / 长上下文请求会漏到别处。
- 路由器会合并内置默认 provider,
ccr health长期显示System degraded+codewhisperer-primary ❌—— 无害,别去修。 (opencode-zen ❌也可能出现,因为 health 探活方式与实际 messages 调用不同; 只要经/v1/messages能拿到真实回包,就是通的,别被 health 误导。) - 免 key 上游:
"apiKey": ""即可,路由器会省略 Authorization 头 → Zen 视为匿名。 填任何非空假 key 反而会被 Zen 拒(AuthError: Invalid API key.)。 - 强制推理模型(Space Bunny)
max_tokens要给足,否则推理 token 吃光预算、 返回content: [](表现为"空回复",不是坏了)。
Claude Code 侧 settings.json
"env": {
"ANTHROPIC_AUTH_TOKEN": "<本地网关令牌>",
"ANTHROPIC_BASE_URL": "http://127.0.0.1:3456",
"ANTHROPIC_MODEL": "space-bunny[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "space-bunny[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "space-bunny[1m]",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "space-bunny[1m]",
"ANTHROPIC_DEFAULT_FABLE_MODEL": "space-bunny[1m]",
"CLAUDE_CODE_SUBAGENT_MODEL": "space-bunny[1m]",
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
"API_TIMEOUT_MS": "600000"
}
ANTHROPIC_AUTH_TOKEN这里是本地网关的令牌,不是上游真 key —— 真 key 只存在网关 config 一处,不随settings.json扩散。网关会校验这个令牌:不带或带错直接 401,其它本地进程 无法白用你的上游额度。- 令牌在网关首次启动时自动生成并写进
~/.claude-code-proxy.json;ccswitch.py会把它 同步到settings.json与各网关 profile,两端始终一致(手工写router-local之类的占位值 也能跑,会被自动替换为真令牌)。 - 1M 上下文的模型用
[1m]后缀 +AUTO_COMPACT_WINDOW=1000000。
配进 WorkBuddy 客户端(~/.workbuddy/models.json)
GUI 里「配置自定义模型」写的就是这个文件(顶层数组或 { "models": [ ... ] } 都合法)。
除了 Claude Code,也可以让 WorkBuddy 本体直接选第三方模型:
{
"id": "space-bunny-free",
"name": "Space Bunny",
"vendor": "OpenCode Zen",
"url": "https://opencode.ai/zen/v1/chat/completions",
"apiKey": " ",
"supportsToolCall": true,
"supportsReasoning": true
}
⚠️
apiKey不能留空字符串(这是最容易踩的坑)。运行时(codebuddy-headless.js) 取 key 的逻辑是:js ei = settings.env.CODEBUDDY_API_KEY || process.env.CODEBUDDY_API_KEY; // 默认 = 平台 token if (model.apiKey) ei = model.apiKey; // 有值才覆盖 if (ei) headers['x-api-key'] = ei, headers['Authorization'] = `Bearer ${ei}`;空串是假值 → 不覆盖 → 客户端把自己的 WorkBuddy 平台 token 当 Bearer 发给上游, 症状是上游回
401 AuthError: Invalid API key.(错误码 3001、category: custom_model_auth), 报错信息会指向「请检查模型配置(API Key、模型 ID、接口地址)」——全是误导, 配置一个字都没错。Claude Code 侧没有这个问题(网关自己管上游鉴权)。修法:把
apiKey填成单个空格" "。上游只会看到Authorization: Bearer, 而匿名型端点会先 trim 再判空,所以照常放行。 实测(http.client直发,不经 curl,避免尾随空格被裁掉):Bearer(token=1 空格)→ 200;Bearer→ 200;Bearer \t→ 200;Bearer \xa0(非断行空格)→ 401 —— 所以必须是 ASCII 空格/Tab,别用全角或不换行空格。 反例:任何非空可见值(含undefined/null/EMPTY/sk-)一律 401。相关环境变量(排查用):
CODEBUDDY_API_KEY(key 本体)、CODEBUDDY_API_KEY_DISABLED=1(设了则整套 key 逻辑短路、完全不发 Authorization 头 —— 这是最"干净"的关掉方式,但它会同时影响 WorkBuddy 自己的内置模型,慎用);CODEBUDDY_CUSTOM_HEADERS(附加自定义头)、CODEBUDDY_DISABLE_CUSTOM_MODELS_FILE=1(不读 models.json)。
models.json的用户级文件有 watcher(1s 去抖)+ 每次请求重新读 config, 改完通常不必重启客户端,直接重发即可;不行再重启。用户级apiKey还可能在 保存时被凭据编解码加密(WBEF1前缀),读到明文不受影响。
诊断:怎么拿完整出站请求体(关键)
网关会把上游错误包装掉,只留一句 openrouter request failed: Request failed with status code 400,看不出是 auth 还是 body 格式问题。拿真实 body 的方法:
- config 里开
"traceRequests": true(配合saveRequests),重启网关; - 发一次测试请求;
- 从日志里用 node 解析 axios 的
config.data(日志里该字段会被截断,别直接肉眼看):
node -e "
const fs=require('fs');
fs.readFileSync('<logDir>/ccr-2026-09-29.log','utf8').split('\n').filter(Boolean).forEach(l=>{
const o=JSON.parse(l);
if(o.level==='error'&&o.data?.config) console.log(o.data.config.data, JSON.stringify(o.data.config.headers));
});"
A/B 判据:同一个无效 key,直连 OpenRouter 返回 401 Missing Authentication header,
而经网关返回 400 —— 两者都是 auth 被拒,只是 OpenRouter 对网关来源的错误码不同。
拿到合法 OpenAI 格式 body 且模型名正确 = 链路已通,剩下只是换真 key。
(判断 body 是否合法:形状应是
{"model":"stealth/space-bunny-alpha","messages":[...],"max_tokens":N,"stream":false})
启动
网关必须常驻,且不能用 nohup ... &(会随命令进程组被杀,见 Step 8)。
用工具自带的后台运行能力起,或给用户建启动器(本机已固化,见第六 / 七部分):
# 前台起网关(窗口可见,保持开着)
python scripts/ccproxy.py --port 3457 --verbose
# 或让切换器代劳(推荐):它判定是否真需要网关、避免重复启动
python scripts/ccswitch.py gateway
脚本随本技能提供,位于
scripts/目录下 ——ccproxy.py(网关)+ccswitch.py(切换器)。 纯 Python 标准库、零第三方依赖,拷到任意位置都能跑。 Windows 用户想双击即用,可自建.cmd启动器(内部先chcp 65001防中文乱码), 内容就是上面那两行命令。 注意 CC 2.1.278 起bin指向原生claude.exe(不再有cli.js);claude.cmd只是批处理包装。
已知限制
Space Bunny 是强制推理模型,默认 effort 较高(偏慢)(模型已下线,2026-10-16)。 现役的deepseek-v4.1-flash-free同样支持六档 effort(minimal/low/medium/high/xhigh/max), 但 Claude Code 的CLAUDE_CODE_EFFORT_LEVEL经网关未必能传下去(同 Step 9, 很可能是空操作),需要实测确认。- 匿名 stealth 模型规格/数据政策未公开(提供方可能保留 prompt,不用于训练), 别用于高敏感或强合规场景。
第六部分:多 profile 一键切换(ccswitch)
目标:用户说一句「切 deepseek」/「切 zen」就完成切换,不再手工改配置。
用法
python scripts/ccswitch.py deepseek # 切到 DeepSeek 原生端点
python scripts/ccswitch.py zen-ds-flash # 切到 Zen 免费模型(自动拉起桥接+网关)
python scripts/ccswitch.py status # 当前 profile + 网关状态
python scripts/ccswitch.py list # 列出所有 profile
python scripts/ccswitch.py gateway # 只确保网关在跑
python scripts/ccswitch.py <p> --no-gateway # 只改 settings,不动网关
别名:ds/deepseek-flash→deepseek,zen/opencode-zen/zen-ds/ds-flash→zen-ds-flash。
🗑️
spacebunnyprofile 已于 2026-10-16 随模型下线移除。旧别名bunny/sb/space-bunny现在统一指向zen-ds-flash,不会再报「unknown profile」。
删除模型(免费模型过期/失效时用)
免费模型说没就没,删一个模型的所有入口(切换器 GUI、ccswitch list)立即失效,
不用改代码、不用重新部署:
python scripts/ccswitch.py delete <profile> # 交互确认(y/N)
python scripts/ccswitch.py delete <profile> --yes # 跳过确认
python scripts/ccswitch.py delete <profile> --permanent # 连付费模型也真删
免费模型是真删,付费模型才归档:
- profile 带
"x_free": true→os.remove直接删除,不留 backup (免费模型要么不好用、要么已失效,没有保留价值;想重建随时加回来)。 - 付费模型(用自己的 key,如 deepseek)→ 移入
~/.claude/backups/deleted/, 想恢复就拷回profiles/。 --permanent可强制真删任何 profile(含付费)。ccswitch list会显示[free]/[paid]标记,删前可分辨。
其它注意:
- 删的是当前生效的 profile 时会警告:
settings.json本身不动,但从此没有 profile 与它对应,删完建议再切一个别的模型。 - 删不存在的 profile 直接报错并列出现有 profile,不会误伤。
- GUI 切换器(
claude_model_switcher.pyw)底部有同样的「删除所选模型」下拉框, 下拉显示「显示名 [profile名]」(分得清免费/付费),免费模型确认弹窗会明示 「永久删除、不留 backup」,逻辑与 CLI 一致。
设计(可直接照搬到别的工具)
- profile 即模板:
~/.claude/profiles/<name>.json存一份完整的 Claude Codesettings.json;切换 = 复制覆盖~/.claude/settings.json。 - 切前必备份:旧文件存
~/.claude/backups/settings.json.bak-<时间戳>; 与目标内容相同则跳过(不刷屏)。 - 是否需要网关由配置自身推出,不靠额外元数据:
ANTHROPIC_BASE_URL含127.0.0.1:3457→ 需网关(切过去自动拉起、切走自动停); 其它(如api.deepseek.com/anthropic)→ 原生端点,不需要网关。 - 网关本体是
ccproxy.py(第七部分),不是 claude-code-router; 停网关:netstat -ano找:3457 LISTENING→taskkill /F /PID。 - 新增模型 = 丢一个 profile json 进去,脚本自动出现在
list里。 - 令牌自动对齐:网关的
client_token与settings.json的ANTHROPIC_AUTH_TOKEN由切换器统一同步(仅在空值/占位值时生成新令牌),用户不用手抄令牌,两边也不会漂移。
关键提醒
- 切换后必须重启 Claude Code(已开会话仍持旧 settings)—— 脚本会打印这句。
- 脚本在
scripts/下,跨平台:Windows 走netstat+taskkill, macOS / Linux 走 pidfile +SIGTERM。 - 想让 Windows 用户双击即用,自建
.cmd启动器即可(内部chcp 65001防中文乱码), 内容就是python <技能目录>\scripts\ccswitch.py <profile>。
本机坑(2026-09-29)
| 现象 | 真相 |
|---|---|
Popen 起的网关活不过本次调用 | 以后台方式启动(Bash 的 run_in_background),或让用户用 .cmd 启动器双击运行 |
/tmp/sb.json 写得出、Python 打不开 | Git Bash 的 /tmp 是虚拟路径,原生 Python 看不见。落盘要写 Windows 真实路径,或直接走管道 |
→ 结论:验证链路优先「直连端点」,别依赖拉起完整 CC;网关的常驻方式见第七部分。
第七部分:ccproxy —— 自建零依赖 Anthropic↔OpenAI 网关(2026-09-29)
为什么自建:见第五部分的更正。claude-code-router 的 SSE 转换是坏的,
且它只有 2 个版本、无新版可升,2MB 压缩产物 + 超长行无法可靠打补丁 —— 与其修,不如替换。
文件清单
| 路径 | 作用 |
|---|---|
scripts/ccproxy.py | 网关本体(Python 3 stdlib,零第三方依赖,约 740 行) |
scripts/ccswitch.py | profile 切换器 + 网关启停协调(跨平台,约 515 行) |
scripts/zen_bridge.py | OpenAI <-> opencode SDK 桥接(零依赖,约 668 行);--provider 切默认 provider,请求里写 provider/模型名 可单次覆盖 |
~/.claude-code-proxy.json | 配置:host / port / upstream{url,model,api_key} / timeout / verbose / client_token |
examples/claude_model_switcher.pyw | 桌面 GUI 切换器(双击即用,含删除/刷新模型;~/.local/bin 同名文件应从此处同步) |
examples/profiles/*.json | 开箱可用的 settings.json 模板,拷到 ~/.claude/profiles/ |
python ccproxy.py --port 3457 --verbose # 前台带日志
python ccproxy.py --upstream <url> --model <name> --key <k> # 临时换上游
curl -s -H "x-api-key: $TOKEN" http://127.0.0.1:3457/health # {"ok":true,"service":"ccproxy",...}
CLI 参数优先于配置文件(且不会被写回配置文件)。当前上游(本机现役):
http://127.0.0.1:8787/v1/chat/completions(= 本地 zen_bridge,再经 opencode SDK 到 Zen)
deepseek-v4.1-flash-free+ 空 api_key。 (旧写法https://opencode.ai/zen/v1/chat/completions+space-bunny-free已随模型下线失效: 直连 Zen 现在一律FreeTierError。见第八部分。)
安全设计(默认即如此,不用额外配置)
网关是本机进程与「你的上游额度」之间唯一的关口,所以默认做了这几件事:
| 机制 | 做法 | 作用 |
|---|---|---|
| 客户端令牌鉴权 | client_token 首次启动自动生成(secrets.token_urlsafe(24));/v1/messages 与 /health 都校验,不符返回 401 | 其它本地进程无法把它当免费中转、白用你的上游凭证 |
| 只监听回环地址 | 默认 host=127.0.0.1;若被改成非回环地址,启动时打印显式警告 | 不把网关暴露到局域网 |
| 对端身份校验 | ccswitch 的健康检查要求响应里 service == "ccproxy",否则判定「端口被其它进程占用」并报错,不再盲信端口 | 防止端口被别的程序占住后冒充网关、截走 prompt |
| 不读代理环境变量 | 上游走 http.client | 不受系统代理影响(见第五部分) |
| 改动有痕迹 | 令牌只写回配置文件的单个键(CLI 参数不落盘);切档前自动备份 settings.json 到 ~/.claude/backups/ | 可回溯,不静默改你的环境 |
边界说明:令牌存放在本机配置文件里,同一用户下的其它进程本就能读到该文件。它挡的是 「本机程序顺手把网关当免费通道」,不是同用户内的强隔离;需要强隔离就用独立系统账号跑网关。
实现要点(照着抄,别重蹈覆辙)
- 上游用
http.client直连,不用 requests/axios → 不读取HTTP_PROXY/HTTPS_PROXY这类代理环境变量,从根上避免第五部分那类「请求被系统代理接管」的问题。 - 事件序列严格合规(这正是路由器翻车处):
message_start(恰 1 次) →content_block_start→content_block_delta* →content_block_stop→ (下个块同理)→message_delta(带真实stop_reason)→message_stop(恰 1 次)。 - 异常也必须收尾:上游中途断开 / 报错 / 返回空内容时,仍要补发
message_delta+message_stop(必要时补一个空 text block),绝不裸断 —— 这是stream was malformed的根治手段。 - 工具调用:多个 tool_call 的
arguments增量会交错到达,因此 不要在某个 tool 块出现时就关闭前一个块;让所有块保持 open,结束前按 index 顺序统一 close。arguments片段直接映射为input_json_delta.partial_json(CC 自己拼接)。 finish_reason→stop_reason:stop→end_turn、length→max_tokens、tool_calls/function_call→tool_use。reasoning_content直接丢弃:Anthropic 的 thinking block 需要signature,伪造易炸。 (想要思考过程再加开关。)- 上游常不给 token 数 → 用
字符数 / 3.5估算input_tokens/output_tokens, 够 CC 显示成本与 auto-compact 用。 - 请求侧映射:
system→role=system;user 里的tool_result块要拆成独立的{"role":"tool","tool_call_id":...};assistant 的tool_use→ OpenAItool_calls;tools[].input_schema→function.parameters;tool_choice:any→required、tool→{type:function,function:{name}};thinking.budget_tokens→reasoning_effort。 - 入站先鉴权:
do_POST/do_GET开头部用hmac.compare_digest比对x-api-key(或Authorization: Bearer)与client_token,不符返回 401 的 Anthropic 错误体。 少了这一步,本机任何进程都能把你的上游额度当免费 API 用。 - 健康检查要能证明身份:
/health返回{"service":"ccproxy","pid":...}且要求令牌; 调用方校验service字段,端口被别人占住时报错,而不是当成「网关已就绪」。 - 只把令牌写回配置文件的那一个键:CLI 覆盖项(
--port/--verbose/ …)不能落盘, 否则调试用的临时参数会污染用户配置。
验证方法(必做,别凭感觉)
TOKEN=$(python -c "import json;print(json.load(open(r'C:/Users/<u>/.claude-code-proxy.json'))['client_token'])")
curl -sN http://127.0.0.1:3457/v1/messages \
-H "x-api-key: $TOKEN" \
-H 'content-type: application/json' -H 'anthropic-version: 2023-06-01' \
-d '{"model":"x","max_tokens":300,"stream":true,"messages":[{"role":"user","content":"回答两个字:你好"}]}' > out.txt
逐块解析 event:/data: 后检查(实测通过的样子):
| 检查项 | 期望 |
|---|---|
不带令牌打 /health 或 /v1/messages | 401(鉴权生效,实测如此) |
/health 带令牌 | {"ok":true,"service":"ccproxy","pid":...} |
message_start / message_delta / message_stop 计数 | 各 1 |
content_block_stop 计数 | = content_block_start 计数 |
| 首 / 末事件 | message_start / message_stop |
| text 拼接 | 等于完整回答(实测 '你好') |
| 带 tools 时 | 出现 content_block_start(type=tool_use) + input_json_delta,args 能 json.loads 成功(实测 {"city": "北京"}),stop_reason=tool_use |
| 真实 CC | claude.exe -p "7*8=?" --output-format json → result:"56"、stop_reason:"end_turn"、is_error:false |
本机坑(与网关相关)
- 验证 CC 时优先用原生二进制入口(比
claude.cmd这层批处理包装更稳):~/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code/bin/claude.exe(CC 2.1.278:package.json的bin=bin/claude.exe,不再有cli.js,别再按老路径找)。 - 该 exe 体积约 237MB,首次
ls会略慢,正常。
大 payload 才是真凶(2026-10-07 实测,v1.3.0)
前面两节修的是「持续性故障」。这一节是残余的间歇故障,机制完全不同。
决定性数据
同一网关、同一时刻、同一 payload,只改变一个变量:
| 场景 | 结果 | 耗时 |
|---|---|---|
| 16B token 小请求(顺序·直连) | 10/10 | 4.0s |
| 183KB 真实 payload(顺序·非流式) | 3/3 | 34-47s |
| 183KB(顺序·流式) | 2/2 | 24-36s |
| 183KB(并发 4·流式) | 4/4 | 35-37s |
| 183KB(并发 4·非流式) | 4/4 | 44-45s |
| 183KB(并发 4·流式·经代理) | 4/4 | 15-33s |
两个关键推论:
- 并发不叠加(4 并发仍 45s,不是 180s)→ 排除客户端压力/连接池问题。
- 经代理反而快约 40% → 直连走的不是最优路由。
10054 的真实机制
不是断连,是超时。 183KB 请求让免费端点的轻量模型算 40 秒左右,
Cloudflare 边缘节点在这个时长附近会掐掉仍在处理中的连接,
网关侧看到的就是 ConnectionResetError。
26 次重放里一次 RST 都没复现——所以别再指望抓到它。
哪些请求是「大 payload」
挖failures.jsonl 的 openai_body 就能认出来,特征很硬:
| 特征 | 分类器请求 | 正常对话 |
|---|---|---|
| body 体积 | 178-183 KB | 小 |
| system prompt | 140 KB | 小 |
max_tokens | 2112 / 10240 / 32000 | 正常 |
stop_sequences | ['</block>'] | 无 |
| 结尾 | MUST begin with <block> | 无 |
这是 Claude Code 的 Bash 安全分类器,不是用户对话。
所以报错是 auto mode cannot determine the safety of Bash,
表现为「Bash 工具卡住不动」。
修法B:自动重试(retries / retry_backoff)
def open_upstream_with_retry(oa_req):
# 只重试传输层故障,绝不重试上游给出的 4xx/5xx —— 那是答案不是意外
流式中途失败只在「一个字节都没吐给客户端」时才重试,
用 emitted 高水位追踪:已吐内容就重放会导致重复输出,
这时失败比重复更诚实。
新增配置(默认值已写进 DEFAULT_CONFIG):
{ "retries": 2, "retry_backoff": 1.5 }
退避是 backoff * 2**i(1.5s → 3s)。
修法 C:走代理(resolve_upstream_proxy)
优先级:upstream.proxy 显式配置 > HTTPS_PROXY/HTTP_PROXY 环境变量 > 直连。
配置里不写 proxy 键就是「自动跟随环境变量」,
VPN 换端口时无需改配置。
实现用 CONNECT 隧道(conn.set_tunnel),
不是绝对形式请求目标 —— 这样 TLS 端到端,request-target 保持 origin form,
流式才能正常工作。实测快 40%。
验收结果(v1.3.0)
/health200、非流式 200、流式 SSE 六事件齐全- 178KB 真实分类器 payload → 200
- 真实
claude.exe多轮工具调用全200,含绝对 URI 形式 - failures.jsonl 停在 29 条,新版本零新增
诊断顺序(补充)
- 先看
failures.jsonl里openai_body的体积和max_tokens, 别一上来就查网络连通性 —— 小请求能通不代表大请求能通。 - 用捕获的真实 payload 重放,小请求测不出这个问题。
- 网关启动时打印
upstream route:和upstream retries:。 没有这两行,代理是否生效完全不可见 —— 排查时先确认它们。
第四部分:Zen 免费模型的两段式链路(2026-10-16)
OpenCode Zen 的免费模型(如 deepseek-v4.1-flash-free)不能直连,也不在
opencode models 的 catalog 里;只有把请求包成 opencode 自己的会话才能用。
所以链路变成两段中继:
Claude Code ──Anthropic──> ccproxy:3462 ──OpenAI──> zen_bridge:8787 ──SDK──> opencode serve:41234 ──> Zen
WorkBuddy ───────────────── OpenAI ───────────────> zen_bridge:8787 ──┘
scripts/zen_bridge.py(零依赖单文件)负责 OpenAI <-> opencode SDK 的转换,
opencode serve 由桥接用 --auto-start 自动拉起。
免费模型自动换血(--autopick)
免费池会随时失效/变慢,所以桥接支持启动后顺手体检一遍:
python zen_bridge.py --port 8787 --sdk-port 41234 --auto-start --autopick
# --autopick-delay 25 默认延迟 25s 再开始,先让桥接能服务请求
它是后台线程,跑的是 free-llm-installer 技能的
install_free_llms.py --auto:只测当前已装的 N 个,掉队了才全量重选,
并写回 ~/.workbuddy/models.json。桥接侧完全不等它,请求照常走。
三道刹车(都在 install_free_llms 一侧,避免被免费池抖动带偏): 单次失败重试一次 → 巡检最小间隔 20 分钟 → 全量重选冷却 6 小时。
⚠️ 这里的 sys.executable 有坑:桥接原本没 import sys,--autopick 一跑就
name 'sys' is not defined,而且因为在线程里只写日志、不影响服务,很容易漏掉。
改这块务必看一眼日志里有没有 autopick 执行失败。
~/.local/bin/zen_bridge_supervisor.pyw 是配套守护:每 20s 探 /health,
挂了自动 --auto-start --autopick 重启(登录自启见启动文件夹的 VBS)。
换 provider / 换模型(桥接已支持)
桥接不限制模型名:KNOWN_FREE 只是 /v1/models 的展示清单,build_payload()
直取请求里的 model 字段转发。约束只在 provider 上,且现在可配:
# 1) 启动时指定默认 provider(默认 opencode)
python zen_bridge.py --provider siliconflow --model Qwen/Qwen3-8B
# 2) 或在请求里单次覆盖:model 写成 "provider/模型名",按第一个斜杠切分
curl http://127.0.0.1:8787/v1/chat/completions -d '{
"model": "deepinfra/anthropic/claude-fable-5",
"messages": [{"role":"user","content":"hi"}]}'
按第一个斜杠切分,所以模型 id 自身含斜杠也能正确解析
(deepinfra/anthropic/claude-fable-5 → provider=deepinfra + model=anthropic/claude-fable-5)。
⚠️ opencode 有 230 个 provider,但绝大多数没配 API key:opencode 只是列出了模型目录,
调用时没有凭据会在发消息阶段返回 500(注意:建会话仍返回 200,不能拿建会话成功当可用性判据)。
opencode 这个 provider 是特例——Zen 免费层走客户端鉴权,所以不配 key 也能用。
实测能出字的(2026-10-16,opencode provider 下):deepseek-v4.1-flash-free(2.0s)、
big-pickle(2.0s)、space-bunny-free(1.7s)。
空壳/不可用:muse-spark-1.3-contributor-free、cat-jam-free(parts=[] 无输出);
nemotron-3-ultra-free(180s 超时)。
profile 的自描述字段(x_*)
带 x_ 前缀的键是 ccswitch 专用提示,永远不会被写进 settings.json
(strip_internal() 会剥掉),也不参与 same_json 比对:
| 字段 | 作用 |
|---|---|
x_bridge: true | 切换时先确保 zen_bridge 在跑 |
x_gateway_port | 该 profile 专用的 ccproxy 端口(不同上游不能共用一个端口) |
x_ccproxy_args | 传给 ccproxy 的 --upstream/--model/--key,避免污染共享的 ~/.claude-code-proxy.json |
示例见 ~/.claude/profiles/zen-ds-flash.json。ccswitch 和桌面 GUI
(examples/claude_model_switcher.pyw,本机位于 ~/.local/bin/claude_model_switcher.pyw)都认这三个字段。
四个必须记住的点
- ccproxy 忽略请求体里的 model(源码 408 行只取
CONFIG["upstream"]["model"]), 所以 profile 里写xxx[1m]只影响 UI 显示,实际转发永远是--model指定的值。 - 工具调用是靠提示词模拟的:opencode SDK 的
tools字段只接受{工具名: true/false}开关内置工具,注册不了外部 OpenAI 工具。做法是把工具清单- JSON 契约喂给模型,再解析成标准
tool_calls。
- JSON 契约喂给模型,再解析成标准
- 工具指令必须放用户消息里,放
system会被 opencode 的 agent 提示压掉 —— 实测放 system 时模型转头用内置工具干活,把ls结果写成中文叙述,还耗时 148 秒。 但身份类指令放 system 是有效的(弱约束不会被压)。 - 冷启动约 9-10 秒(桥接 +
opencode serve);热调用 2-6 秒。 切换器的ensure_bridge()会轮询/healthz等待就绪,不要缩短那个超时。
已知限制
- 无 tools 的 stream 请求已支持真流式(2026-10-18 起):
prompt_async+ 订阅/event,增量是message.part.delta(field='text'),完成信号是session.status的 busy→idle。首字延迟从「整段」降到「第一批增量」(实测 200 字短文 5.9s→1.1s)。 订阅/prompt 前的异常自动降级为整段返回;--no-upstream-stream可整体关掉。 坑:session.status有busy/retry/idle三态,免费池限流时上游会 busy→retry 反复。只有 idle 才算结束——早期版本把「非 busy」当结束, 结果限流重试时提前断流、返回空回复(glm-5.3 实测 0.8s 空 vs 修好 77s 正常)。 - 多轮工具调用的历史序列化(2026-10-18 修):助手发起工具调用那条消息
content通常是null,早期版本把它放在if txt:里 → 整条调用记录从历史消失, 模型只看到「提问 + 孤立工具结果」,第二轮必重复调同一个工具,agent 循环跑不起来。 现在 assistant+tool_calls 单独处理、序列化成assistant: called fn(args), 并在工具指令里加了「已有 tool result 就别重复调」的约束。 - 带 tools 的请求仍整段返回:工具调用靠提示词模拟,流式吐到一半才发现是
工具调用会同时泄出正文 JSON,不如整段回来再判。对 Claude Code 无影响
(事件序列依然合规,含
message_stop)。 - 桥接复用已运行实例,所以首次之后改桥接代码/启动参数不会生效 —— 要改就得先停掉它。
附篇 · 脚本级切换 LLM 端点的坑(OpenAI 兼容第三方,适用于 WorkBuddy / 任意 Python 客户端)
原
llm-endpoint-switching技能(2026-10-19 并入)。上面各章是 Claude Code 侧的接入与代理基建; 本附篇是写脚本 / 客户端代码时切端点的高频坑,与基建层互补。
核心结论
OpenAI 兼容端点之间迁移,通常只改 base + model 两个值,请求体不用动。 但有两件事会咬人,且都会伪装成「key 无效」或「参数错误」。
坑一:⚠ 第三方端点前面挂 Cloudflare,urllib 默认 UA 被拦
症状:HTTP 403,响应体是 error code: 1010(有时只有这一个数字,
没有 JSON、没有 errmsg)。
根因:urllib.request 的默认 User-Agent 是
Python-urllib/3.x,Cloudflare 的 WAF 规则直接拦下。这不是鉴权问题,
换真 key 也照样 403——因为请求根本到不了鉴权那一步。
2026-10-01 实测(OpenCode Zen / Space Bunny):
| 请求头 | 结果 |
|---|---|
| 默认(无 UA) | HTTP 403 {"error code": 1010} |
User-Agent: Mozilla/5.0 … Chrome/126.0 | HTTP 401 Invalid API key |
403 → 401 的转换本身就是结论:请求形状已经通了,只差 key。
修法(每次请求都带上,不是只在抓网页时带):
req = urllib.request.Request(
url, data=body,
headers={"Content-Type": "application/json",
"Authorization": "Bearer " + key,
"User-Agent": UA, # ← 关键,别漏
"Accept": "application/json"})
⚠ 别只在抓网页的函数里带 UA,LLM 请求单独漏掉——这个漏项极隐蔽, 代码看着没问题,但一换端点就403,而且所有人都会先怀疑 key。
坑二:先ping 再跑批量
换端点后先发一个极短请求验通,别直接跑一批 20 条核验任务。 一次核验的思考 token 可能上千,key 不对就是白烧时间和额度。
实现要点:ping 不碰任何业务数据、不写任何文件,只发一个 「只回这个 JSON」的请求并打印耗时。
##状态码分诊(别一律报「调用失败」)
这四类指向完全不同的问题,混在一起会让人白排查半天:
| 状态码 | 真实原因 | 下一步 |
|---|---|---|
| 403 | Cloudflare/WAF 拦 UA | 补浏览器 UA(不是 key 问题) |
| 401 | key 无效 / 没这个订阅 | 换 key、查订阅状态 |
| 404 | base 或 model 名写错 | GET <base>/models 列可用值 |
| 400 | 参数被拒 | 多半是 response_format 或 max_tokens 超上限 |
400 最常见的两个原因:
- 端点不支持
response_format={"type":"json_object"}—— 部分第三方端点(尤其聚合/中转站)不支持, 而有些脚本的 JSON 解析链路硬依赖它。 ⚠ 这时要权衡:要么换端点,要么给该端点单独走「提示词里要求返回 JSON- 代码里容错解析」的降级路径,别默默把 JSON 模式关掉。
max_tokens超过端点上限 —— 换个更小的值试。
推理模型的 max_tokens 陷阱
思考 token 也计入 max_tokens。核验类任务(要塞进几万字网页原文、
要求结构化输出)实测一条要烧 4000+ token,其中思考可能占 3600。
⇒ 把上限放宽到能容纳「思考 + 正文」,并在 finish_reason == "length"
时明确报错(内容被截断,JSON 不完整,硬解析会得到莫名其妙的结果):
if ch.get("finish_reason") == "length":
raise RuntimeError("LLM 回答被 max_tokens 截断(finish_reason=length)"
"——模型思考太长,正文没输出完整 JSON")
⚠ 别拿「超时」当失败结论,但 finish_reason=length 是真实截断,必须处理。
base 拼接约定
base = "https://example.com/v1" ← 填到 /v1,不要带 /chat/completions
url = base + "/chat/completions"
base 尾部斜杠会被 rstrip,但 base 里必须包含版本段。
写了 /v1/ 和 /v1 效果一样;写成不带 /v1 会在拼出
/chat/completions 时404。
配置注入的两种方式
# 1) 环境变量(适合容器/CI,密钥不进代码)
BASE = os.environ.get("X_AI_BASE", "https://api.deepseek.com").rstrip("/")
MODEL = os.environ.get("X_AI_MODEL", "deepseek-chat")
KEY = os.environ.get("X_AI_KEY", "")
# 2) 运行期 configure()(适合后台 GUI 存密钥、CLI 临时切换)
def configure(api_key=None, base=None, model=None):
"""不传的项保持原值 —— 后台存 key 就靠这个语义。"""
global KEY, BASE, MODEL
if api_key: KEY = api_key
if base: BASE = base.rstrip("/")
if model: MODEL = model
configure(model="new-model") # 只换模型,沿用原 base/key
⚠ configure() 必须「不传的项保持原值」——如果写成整体覆盖,
后台只存了 key 却把 base/model 清空了,会表现为「存了密钥反而连不上」。
测试怎么写
这几条值得钉死,否则下次重构会静默回归:
- 请求头必须有浏览器 UA —— 用假的
urlopen捕获请求对象断言 (这是本次唯一的真 bug,最该被回归钉住)。 configure()只覆盖传入项(断言只传 model 时 base/key 不变)。- ⚠
configure(api_key="")必须真清空 key —— 用真值判据会静默跳过空串, 免 key 端点必401。这条是 2026-10-04 的事故,务必钉死。 configure()会 rstrip base 的尾部斜杠。- ping 在没 key 时不联网且返回非零。
- ping 对 403/401/404/400 给出各自不同的诊断文案。
- ⚠
ai_ready()/is_no_key_endpoint()的判断口径(无 key 但免 key 端点 → 就绪)。
⚠ 断言请求头时注意 dict(req.headers) 的键是小写,
self.assertIn("Authorization", headers) 会假失败。
⚠⚠ 坑三:切到免 key 端点时,空串是真值陷阱(2026-10-04 血案)
从付费端点(DeepSeek 等)切到免 key 端点时,要改的不只是 base + model。 下面每一条都实测撞过,不是理论风险。
3.1 configure() 用真值判据 ⇒ 旧 key 清不掉 ⇒ 必 401
# ❌ 错的写法
def configure(api_key=None, base=None, model=None):
if api_key: # ← "" 是 falsy,空串被跳过!
KEY = api_key
# ✅ 正解:判据是 is not None
def configure(api_key=None, base=None, model=None):
if api_key is not None:
KEY = api_key
实测后果(2026-10-04,OpenCode Zen / Space Bunny):
| 场景 | 结果 |
|---|---|
空 Bearer(AI_KEY = "") | ✅ 200 |
| 带着旧的 DeepSeek key | ❌ 401 Invalid API key |
后台 GUI「保存」时通常传空串表示「清空 key」—— 真值判据下这个请求
静默不生效,旧付费 key 被沿用,于是拿付费 key 打免 key 端点,必 401。
排查这类 401 时第一件事是打印 AI_KEY 到底是不是空,别盯着 key 有效性查。
⚠ 同一个坑还有 CLI 侧:if args.ai_key or args.ai_base or args.ai_model
会把 --ai-key ""(显式清空)当成「没传」。用
any(v is not None for v in (...))。
3.2 切端点时旧 key 要删干净,不能只改 base/model
配置文件里留着 ai_key 字段 = 每次调用都发付费 key → 401。
正确做法是整个字段删掉,不是留空串(留空串在某些读取侧等价于「有值」)。
3.3门禁别拿「有没有 key」当「能不能运行」
免 key 端点压根没有 key,所以任何 if not key: return 400
的门禁都会把这类配置全挡在门外 —— 表现为「配置明明对了但点运行就报错」。
# ✅ 单一判据,CLI / 后台 / 前端共用
NO_KEY_HOSTS = ("opencode.ai/zen",)
def is_no_key_endpoint(base=None):
return any(h in (base or AI_BASE or "") for h in NO_KEY_HOSTS)
def ai_ready(key=None, base=None):
k = AI_KEY if key is None else key
b = AI_BASE if base is None else base
return bool(k) or is_no_key_endpoint(b)
⚠ 后台状态接口要同时给三个字段,前端只能看 ready:
{"has_key": bool(k), "ready": ai_ready(k, b), "no_key_endpoint": is_no_key_endpoint(b)}
has_key 对免 key 配置恒为 False,前端拿它判「能不能跑」会把可用配置
误报成「未配置 Key」——用户会以为是配置错了,反复瞎填。
⚠ 门禁里引用配置变量前先确认它已赋值:写成
if not ai_ready(st["key"], ...) 而 st = resolve_ai_settings() 在下一行,
会得到 UnboundLocalError(Python 把它当局部变量),前端表现为
HTTP 000 / 连接被拒,日志里才有真因。
3.4 免 key 与付费端点的能力差异要提前说清
免 key 模型往往更慢(实测单条核验 152 秒 vs 付费端点的秒级),
且自报模型名不可信(实测回显 n="ChatGPT")。
换过去之前告诉用户代价,别让「能跑」被误解成「一样好用」。
「模型列表里有 free」≠「现在能调」(2026-10-01 实测)
要回答「现在有哪些免费模型能用」,必须逐个发真实请求,不能只分析模型名。
实测某端点:GET /v1/models 免 key 就能列出 84 个模型,其中 11 个 id 含
free —— 逐个发真实请求后,只有 1 个真能免 key 调用:
| 真实原因 | 数量 | 能否绕过 |
|---|---|---|
free tier can only be used from within <客户端> | 6 | ❌ 服务端校验客户端来源,伪造 X-Client/Origin/UA 全部无效 |
not available in your country | 2 | ❌ 地区限制 |
| 上游 500 / 模型已下线 | 2 | ❌ 临时故障或下线 |
⇒「模型名带 free」不能当可用性证据。免费模型可用性会漂移,
所以要有个独立探测项目定期发真请求,消费方只读它的档案(ok=true 才用)。
免 key 的正确姿势:发空 Bearer,不是省略
| 写法 | 结果 |
|---|---|
Authorization: Bearer (空值) | ✅ 200 |
完全省略 Authorization 头 | ❌ 挂到超时才报错 |
Authorization: Bearer free | ❌ 401 |
Authorization: Bearer sk-xxx(占位) | ❌ 401 |
服务端会校验 key 是否真实存在,只有空值才走免鉴权分支。
所以「我没有 key」不能表达成 Bearer 无key,只能表达成空值。
⚠ 省掉整个头是最容易踩的写法 —— 表现为超时,不像鉴权问题,很难联想到。
⚠ 档案文件绝不能包含密钥
探测项目若要输出「给别的项目消费」的档案,档案里绝不能有 key:
档案会被 HTTP 接口原样返回,也可能被消费方提交进仓库。
正确做法是只写 no_key: true/false 标记(这个源要不要 key),
key 由消费方自己配。再加一层出站脱敏兜底,防将来回归。
⚠ 写测试时别把漏洞行为固化成断言 —— 「带 key 时 auth 落进档案」这种 断言看着合理,实际是在给泄露开后门。改写成「带 key 时档案里也没有 key」。
Related skills
- Downloads
- Security audit
- Review
- Last updated
- 17h ago
- Current version
- v1.6.0
- License
- MIT-0
