opencodex Claude Code 入站代理生产级加固：错误分类、EOF 熔断、空闲心跳与可观测性闭环（WP1–WP4）

【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载opencodex 通过同端口提供/v1/messagesAnthropic Messages API入站能力让 Claude Code 经ANTHROPIC_BASE_URL指向本地网关后即可路由到任意 LLM 提供商。本文基于开发日志 devlog/_fin/260711_claude_inbound/100_production_hardening.md 中的第四阶段生产加固记录Round 6WP1–WP4结合仓库源码逐项剖析协议一致性修复、错误分类表、EOF 熔断、空闲心跳、surface 可观测性标签与多语言文档闭环。读完本文你将掌握 opencodex 网关层在把非 Anthropic 上游的 Responses 流翻译成 Anthropic 流这一核心链路上如何做到 fail-closed、错误类型对齐官方分类、保活空闲连接以及如何在日志/CLI/文档侧追踪 Claude Code 流量。背景从入站落地到生产加固在 100 号文档之前Claude Code 入站能力已经历了研究000_plan.md、核心入站实现010_phase1_core_inbound.md、Tier-2 协议证据固定003_evidence.md等阶段。其核心架构是translate-and-replay把 Anthropic Messages 请求翻译成内部/v1/responses请求复用既有的路由、OAuth 刷新、账户池、密钥故障转移与 vision/web-search sidecar响应侧再由responsesSseToAnthropicSse把 Responses SSE 事件流逐帧翻译回 Anthropic 消息流src/claude/outbound.ts。100 号文档WP1–WP4是这一功能的生产级加固循环通过 Tier-2 官方文档platform.claude.com 的 errors/streaming/rate-limits/token-counting/handling-stop-reasons 页面与 CLIProxyAPI、LiteLLM 等网关项目的 issue 实证逐条评审入站代理与官方 Anthropic 线协议的偏差并给出 ADOPT/REJECT 结论随后落地为代码修复、可观测性标签与文档更新。WP1 — 差距清单与判定Gap list verdicts加固的第一步是盘点协议偏差。文档以一张评审表列出全部差距与判定这是整轮加固的依据原文结论如下差距Gap判定Verdict理由Rationale错误分类缺少 402/409/413/504ADOPT官方 errors 文档中的完整表格EOF 未带终止帧被当作 end_turnADOPTfail-closed静默截断是网关失败模式 #5CLIProxyAPI#2189Claude Code 需要可重试的error事件无空闲 SSE 心跳ADOPT合成 20sping 事件在任意位置、任意数量均合法保护 LB/NAT 与慢首字节Claude Code 并不强制要求#33949故间隔取保守值incomplete(content_filter)未映射ADOPT →refusal官方 stop_reason 列表包含 refusalstop_sequence恒为 nullREJECTResponses API 不暴露匹配到的 stop 字符串无事实来源count_tokens估算REJECT保留官方 count_tokens 本身也是估算LiteLLM 自带 tokenizer 兜底已在指南中说明/api/hello端点REJECT旧 CLI 连通性探测现行 Claude Code 无需它即可工作在线证据pause_turn/model_context_window_exceededREJECT路由路径上无上游信号可映射原生直通按原样转发surface 标签 GUI 过滤050 后续ADOPTWP3—这套判定把能修、值得修与没有事实来源、不值得伪造的差距清楚分开凡是官方协议有据可依的错误类型、截断语义、refusal、心跳一律 ADOPT凡是上游根本不提供信息源的stop_sequence、pause_turn 映射一律 REJECT——不发明上游不存在的事实是这轮加固的底层原则。WP2 — 协议一致性修复outbound.ts的实现WP2 的所有修复都落在 src/claude/outbound.ts 这一响应翻译器上对应四项改动。1. 错误分类表补齐402/409/504anthropicErrorType(status)是一个纯函数式状态码映射表是 WP2 的直接产物export function anthropicErrorType(status: number): string { switch (status) { case 400: return invalid_request_error; case 401: return authentication_error; case 402: return billing_error; case 403: return permission_error; case 404: return not_found_error; case 409: return conflict_error; case 413: return request_too_large; case 429: return rate_limit_error; case 504: return timeout_error; case 529: return overloaded_error; default: return status 500 ? api_error : invalid_request_error; } }对照源码可见src/claude/outbound.ts413 request_too_large在加固前已存在本次新增402 → billing_error、409 → conflict_error、504 → timeout_error与官方 errors 文档表格逐行对齐未知 5xx 收敛为api_error、未知 4xx 收敛为invalid_request_error。错误体统一由anthropicErrorBody/anthropicErrorResponse产出{type:error, error:{type,message}}信封与 003_evidence.md 固定的官方错误信封一致。2. EOF 无终止帧 → fail-closed翻译器读取上游 Responses SSE 流的循环结束reader.read()返回done时若此前从未收到response.completed/response.incomplete/response.failed等终止帧代码不再礼貌地当作end_turn结束而是抛出可重试的错误事件// EOF without a terminal frame is a TRUNCATION, not success (devlog 100: // gateways that close such streams politely hand Claude Code an empty/partial // turn with no retryable error — CLIProxyAPI#2189 failure pattern). Fail closed // with a mid-stream Anthropic error event so the client can retry. if (!cancelled) fail(502, upstream stream ended before a terminal frame (truncated response), true);见 src/claude/outbound.ts。这里的语义是静默截断是网关失败模式绝不能伪装成正常结束——否则 Claude Code 会拿到一个空/半截的回合且无任何可重试信号。fail-closed 后客户端收到 502api_error即可按策略重试。文档特别指出这与 openai-chat 适配器的 fail-closed 先例保持一致即网关对流被截断统一采取宁可报错、不可错报的策略。3.incomplete(content_filter)→refusalresponse.incomplete事件处理中incomplete_details.reason被分派为三种结局src/claude/outbound.tsmax_output_tokens→finish(max_tokens, usage)content_filter→finish(refusal, usage)本轮的映射修复其余原因 →fail(529, message, true)转成可重试的overloaded_error。refusal是官方 handling-stop-reasons 文档中列出的合法 stop_reason此前未映射意味着内容过滤命中会被错误地呈现为普通结束现在 Claude Code 能按官方语义识别。4. 空闲 keepalivepingIntervalMs默认 20s翻译器构造函数签名接收{ pingIntervalMs }默认20_000mssrc/claude/outbound.ts。行为要点仅在pingIntervalMs 0时启动setInterval定时器定时器触发条件流未终止!terminated且控制器背压允许desiredSize 0避免向已关闭或背压的流继续写入每个周期发出event: ping{type:ping}——按 003 号证据ping 在流中任意位置、任意数量均合法且属于纯传输层事件不会污染message_start → … → message_stop的语义框架定时器在finish/fail/cancel以及读取循环finally中一律clearInterval清理src/claude/outbound.ts保证无泄漏心跳不制造消息注释明确must not manufacture a message before a possible initial error即流开始前的 ping 不构成语义消息。设计动机远程部署场景中 LB/NAT 空闲超时会掐断慢首字节的长空闲连接20s 的保守间隔足以保活同时 Claude Code 并不要求特定心跳节奏claude-code issue #33949因此取较保守值以降低带宽开销。测试佐证WP2 的修复都有对应测试锁定在 tests/claude-integration/claude-outbound.test.tsEOF fail-closed构造无终止帧的流断言输出event: error且消息为upstream stream ended before a terminal frame (truncated response)refusal 映射incomplete(content_filter)的 fixture 断言message_delta.delta.stop_reason refusal心跳时序用 25ms 间隔 fixture 验证 idle ping 的触发与清理分类表逐状态断言anthropicErrorType(402) billing_error、anthropicErrorType(409) conflict_error等完整表格。WP3 — 可观测性surface: claude标签与 GUI 过滤WP3 的目标是让 Claude Code 入站流量在可观测性系统中可被识别与过滤由 worker Feynman 负责实现请求日志打标在 src/server/claude-messages.ts 中/v1/messages处理链将logCtx.surface claude写入 RequestLogContext/Entry桌面版另有claude-desktop变体见同文件 L733count_tokens原生直通路径同样携带该标签L1262。GUI Logs 过滤日志界面提供all | claude | codex分段筛选 带过滤的 virtualizer让用户一键只看某类表面流量。国际化过滤 UI 文案覆盖 x4 语言。请求日志测试对打标行为有对应测试覆盖。这一标签还透出到 CLI 层ocx observe usage与ocx usage命令均支持--surface all|codex|claude|grok参数src/cli/observe.ts、src/cli/registry.ts远程聚合侧也定义了同名的surface枚举src/remote/hub-usage.ts。也就是说从 GUI 日志页到 CLI 用量查询Claude 入站流量与既有 Codex 流量在同一条链路里可被无差别地识别、过滤与统计。WP4 — 文档闭环三语言 Claude Code 指南WP4 由 worker Ohm 负责将加固后的行为同步进用户文档确保代码改了、文档不撒谎。交付物是 Claude Code 指南的多语言版本如 docs-site/src/content/docs/guides/claude-code.md 及其 fr/ 等本地化副本新增四类内容Reasoning effort 一节说明自适应 wire 的思考强度映射Prompt caching 一节breakpoints / affinity / CLAUDE.md 相关说明Token 显示c/w缓存读写 token 的展示约定Production notes 一节错误分类表error taxonomy、Retry-After头处理、count_tokens为估算值的说明——这三者正是 WP1/WP2 落地行为的使用侧写照。文档构建全量通过55 页 clean说明新增内容与既有站点结构无缝衔接。GatesD— 质量闸门整个 WP1–WP4 循环以统一质量闸门收尾bun test2163 通过 / 0 失败tsc类型检查 cleanGUI 构建 clean文档构建 cleanWP2 WP3 WP4 的提交记录在claudecode分支上见 git log。这意味着协议修复、可观测性改动与文档更新是同一批提交、同一套闸门放行避免代码合了、文档欠着的常见漂移。总结一轮可复用的生产加固方法论从 100_production_hardening.md 可以看到生产级加固不是拍脑袋补丁而是一条可复用的闭环以 Tier-2 证据建差距清单WP1每条差距标注 ADOPT/REJECT 及理由官方文档有据可依才采纳无事实来源一律拒绝杜绝虚构协议行为以最小代码面落地修复WP2错误分类、EOF fail-closed、refusal 映射、空闲心跳全部集中在 src/claude/outbound.ts 一个翻译器内改动可审计以测试逐条锁定行为WP3 配套fail-closed、refusal、心跳时序、分类表各有 fixture以标签打通可观测性WP3surface:claude让流量在 GUI Logs、ocx usage --surface、远程聚合间一致可过滤以多语言文档同步语义WP4用户看到的错误、估算、缓存行为与代码实现完全一致。对于任何以翻译代理形态接入第三方客户端的网关项目这套证据先行 — 集中修复 — 测试锁定 — 标签观测 — 文档同步的加固循环都值得直接借鉴。赞分享【免费下载链接】opencodexUniversal provider proxy for OpenAI Codex Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code项目地址https://gitcode.com/gh_mirrors/ope/opencodex点击查看免费下载相关推荐如何快速上手swc-node10分钟从零开始配置TypeScript开发环境如何快速上手swc node10分钟从零开始配置TypeScript开发环境 swc node是一个无需node gyp和postinstall脚本的快速TyOpenUI可观测性实战在生产环境中追踪生成式UI错误OpenUI可观测性实战在生产环境中追踪生成式UI错误 OpenUI 可观测性OpenUI Observability是 OpenUIThe OpenOpenCodex 的 Claude Code CLI 上下文窗口、模型缓存与插槽注入加固实践OpenCodex 的 Claude Code CLI 上下文窗口、模型缓存与插槽注入加固实践 OpenCodex 作为 OpenAI Codex 与 Clau创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考