企业官网建设流程全解析

opencodex（Universal provider proxy for OpenAI Codex & Claude Code）在 Claude 入站（inbound/v1/messages）能力落地的第三个阶段，将 Claude 侧配置从"手改配置文件"推进到"GUI 可视化 + 全文档面覆盖"。本文基于仓库中的 Phase 3 规划文档，结合 GUI 页面源码、管理 API 实现 与 docs-site 指南 等仓库证据，完整讲解/api/claude-code管理接口、侧边栏开关、Claude 配置页、四语言 i18n 同步与三语言文档的落地细节，读者可获得该功能从规划、实现到测试门禁的全链路理解。

一、Phase 3 的定位：让 Claude 侧配置进入现有 Dashboard

在整体规划（见 000_plan.md）中，Claude Code 入站能力被拆分为四个 PABCD 周期：

Phase 3 的核心目标（Objective）非常明确：用户从现有 Dashboard 配置 Claude 侧（D2 决策：不新增独立 app/端口），且所有公开文档面都解释该功能——包括 GUI 配置区、docs-site 文章（3 语言）、README 行（3 语言）。它依赖 Phase 1-2 已交付的config.claudeCode消费与模型发现机制，本身不改变任何入站行为。

值得注意：该文档在 2026-07-11 被用户规格修订（AMENDED），将默认的"Models 页内嵌区块"方案替换为"侧边栏开关 + 独立 Claude 导航页"双入口方案，这一修订直接塑造了今天仓库里的实现形态。

二、管理 API：GET/PUT /api/claude-code

2.1 设计意图

Phase 3 规划在 src/server/management-api.ts 中新增GET/PUT /api/claude-code，用于读/改config.claudeCode，并明确校验规则：

• model id 必须存在于注册表（registry）中或者是别名（alias）；
• modelMap键非空；
• 拒绝未知字段；
• 沿用既有 subagentModels 端点模式，包括saveConfig与 broadcast（变更广播）。

2.2 实际实现：路由与字段面

仓库中的管理路由经过演进，注册于 src/server/management/route-registry.ts，由 src/server/management/agent-settings-routes.ts 处理：

• GET（L1271-L1354）：读取配置并返回完整状态面，包括enabled、三态authMode（auto/proxy/subscription，缺省即 AUTO，不做隐式强制转换）、markerMode、model/smallFastModel/tierModels、modelMap、systemEnv（macOS 系统环境注入开关）、autoContext/autoCompactWindow、maxContextTokens/alwaysEnableEffort等兼容字段，以及webSearchSidecar/visionSidecar覆盖、effectiveModelEnv、available（路由模型列表）与aliases（发现别名预览）。
• PUT（L1355 起）：先做 body 合法性校验（isPlainObject、JSON 解析失败返回 400），再按字段白名单逐项校验；model/tierModels/maxContextTokens/alwaysEnableEffort被标记为config-only back-compat 字段——GUI 已不再提供控件（默认模型由 Claude Code 的/modelpicker 持有），但 PUT 仍校验它们以保护手写配置与旧版 GUI。

从实现看，该端点承担了"配置唯一事实来源的读写代理"角色：GET 负责把 daemon 端检测结果（如authDetection、detectionScope: "daemon"）与别名列表聚合给前端，PUT 负责把 GUI 的增量修改安全落盘并广播。

三、GUI：从侧边栏开关到独立 Claude 配置页

3.1 侧边栏 "Claude ON" 开关

按 030 修订规格，开关应位于 gui/src/App.tsx 的sidebar-foot、语言选择器上方，标签为各语言环境下的字面字符串 "Claude ON"（i18n keyclaude.toggle存在但值在各语言中一致），视觉族与theme-toggle相同，语义为反映并翻转config.claudeCode.enabled（经GET/PUT /api/claude-code）。开关关闭时，入站/v1/messages*路由应答 403permission_error"Claude inbound disabled"，Anthropic 风格发现返回{data:[]}；默认enabled: true（仅环回暴露，开关是紧急停止开关而非"启用仪式"）。

源码演进印证了这一设计：在 App.tsx L388-L391 的注释中明确写道"sidebar 只做导航——没有任何行持有变更"，且"ClaudeCode 现在持有 GET/PUT /api/claude-code，原来的行已移除"。也就是说，后续 GUI 重构把开关从导航区迁移到了 ClaudeCode.tsx 页面顶部的连接头部（claudecode-connection-head），但保留了侧边栏的即时语义：toggleConnection（L131-L153）非乐观更新——等待 PUT 响应后才翻转 UI 状态，因为该开关会写入用户的 Claude 配置文件，若 PUT 失败却显示"已开启"就是欺骗配置；connectionInFlightref 序列化快速连点，避免三次点击产生三次 PUT。

i18n key 的实际落点：app.claudeOn在 en.ts L112 中为 "Claude ON"；后续本地化扩展允许了变体（如 de.ts 的 "Claude AN"、日语 "Claude オン"），且每个语言文件都提供claude.toggleAria无障碍标签（如 en.ts L2641）。

3.2 独立 "Claude" 导航页

030 修订点 2 要求在 App.tsx 的 NAV 条目中、api条目正下方新增{id:"claude", tkey:"nav.claude", Icon:<sparkle/bot-ish lucide>}，渲染新页面 gui/src/pages/ClaudeCode.tsx。当前页面采用"工作台 + 左栏导航"布局，包含五个 section（L207-L252）：

只有 settings / smallFast / modelMap 三个 section 显示 Save 按钮（sectionEditable），quickstart 与 aliases 为只读。save（L155-L188）将整页草稿（含模型映射过滤空行后的modelMap、sidecar 序列化结果）PUT 到/api/claude-code。

草稿机制上，页面用useDataSurface+ 会话缓存（ocx.claude-code.v1:<apiBase>）实现隐藏标签页保持挂载与草稿保留；服务端数据仅在成功读取边界被替换为 draft（保持"保存→重载"行为不变，避免同步副作用）。

3.3 模型发现别名与诚实 display_name

GET/api/claude-code返回的aliases由服务端聚合（agent-settings-routes.ts L1286-L1301）：

• 原生 native slug（经listCatalogNativeSlugs()过滤禁用项）→claudeCodeNativeAlias(slug)，display_name 为"<slug> (native)"；
• 路由模型 →claudeCodeAlias(provider, id)，display_name 为"<model> (<provider>)"；
• 全局 fast 开关开启时，cursor 模型解析为 fast 身份 id，保证 Dashboard 列出的 id 与 Claude Code 实际发现的 id 一致。

这正是 Phase 2 别名层（src/claude/alias.ts，前缀规则：id 必须以claude或anthropic开头）在 GUI 侧的消费端，与 src/server/claude-messages.ts 的入站别名反解（resolveAlias/decodeClaudeFastSelector）构成完整闭环。

四、i18n：四语言同 commit 同步

030 强调仓库惯例（git log 可证）：i18n 同步必须与功能同 commit 交付，新增 key 覆盖gui/src/i18n/{en,ko,zh,de}.ts全部四个语言文件。实际仓库已将语言面扩展至 fr/ja/ru/tr/vi/zh-TW 等，且claude.*key 族（claude.toggleAria、claude.loadFail、claude.saveFailed、claude.saved、claude.smallFastModel、claude.modelMap、claude.aliases、claude.quickstart等）在每一语言文件中成对出现。

防漂移机制方面：030 的风险节提出"de 经常滞后"的担忧，测试计划要求验证是否存在 i18n key 一致性测试，否则新增最小 key-diff 测试。实际验证中，cd gui && bun run build依赖tsc -b强制执行 i18n key 奇偶校验（见 050_close.md 的 gate 证据），使 key 漂移成为编译错误而非运行时缺失。

五、docs-site 文章与 README 行

030 规划在docs-site/src/content/docs/guides/claude-code.md新增英文文章及ko/、zh-cn/翻译，并在 astro.config.mjs 侧边栏注册；内容须覆盖：quickstart（ocx claude）、发现/picker 工作原理（含前缀别名解释）、槽位映射表、非 ocx 启动的手动 env 设置、count_tokens 近似说明、troubleshooting（版本门禁、非环回认证）。

仓库现状完全兑现并超出：指南现存8 个语言版本（en、ko、zh-cn、zh-tw、ja、fr、ru、tr）。指南开头即点明定位：opencodex 在同一端口上提供POST /v1/messages（及count_tokens）与/v1/responses，Claude Code 因此可用所有路由 provider——OAuth 登录、账户池、key 故障转移与 sidecar 全部复用，零额外认证工作。

Quickstart 的环境变量表完整呈现了 src/cli/claude.ts 注入的 env 槽位（仅举关键项）：

用户自行导出的变量始终优先；额外参数透传（ocx claude -p "hello"）。指南还记录了一个微妙的安全修正：Bun 运行时会自动加载项目.env/.env.local，导致目录里的ANTHROPIC_API_KEY曾与手动 export 无法区分、静默把健康订阅切到 API 计费；ocx claude现在忽略仅由项目 dotenv 引入的 Anthropic 凭据，故意用 API key 需显式export。

README 侧：030 要求README.md/README.ko.md/README.zh-CN.md各加一个功能行 + 简短 "Claude Code" 小节，镜像 Codex quickstart 块，作为三语言 README 更新在 050_close.md 中随 WP4 一并交付。

六、测试计划与 C 门禁

030 的测试计划（C gate）包含：

• tests/：management-api claude-code GET/PUT round-trip + 校验拒绝（未知字段、非法 body、空 modelMap）；
• i18n key 奇偶校验（若存在套件模式则复用，否则新增最小 key-diff 测试）；
• cd gui && bun run build（tsc -b）与 docs-sitebun run build（astro check）全绿；
• 视觉检查：GUI section 截图（桌面 + 窄屏宽度）在 D 前评审，文本适配、下拉展开无布局位移；
• 命令门禁：bun test ./tests/、bun x tsc --noEmit+ 上述两个 build。

三条门禁标准（Gate criteria）：

1. 持久性 + 即时路由生效：GUI 修改的配置在 daemon 重启后存活，且实时改变路由（冒烟：切换 small-fast 槽位，在 Logs 中看到 haiku 槽位流量移动）；
2. 文档构建 + 侧边栏链接：本地预览验证，ko/zh 翻译齐全（无占位英文正文）；
3. 全量套件 + 类型检查 + 双 build 全绿。

实际 gate 证据记录在 050_close.md：bun test ./tests/2126 通过（唯一失败为环境既有问题：shell PATH 无 node）；bun x tsc --noEmit干净；GUI/docs-site 双 build 干净（docs-site 55 页）；Playwright 视觉 QA 在隔离 live server（端口 18234）上验证了 Claude 页在 en + ko 渲染、韩语环境下侧边栏开关仍显示字面 "Claude ON"、点击开关完成 APIenabledfalse→true round-trip、别名列表渲染 9 条诚实 display_name。

七、范围边界与风险

Out of scope（030 明确划出）：

• 不改动入站/翻译器行为（发现的 bug 归入 Phase 4，除非阻塞发布）；
• 不新增 de 语言 docs-site（站点仅 en/ko/zh-cn；de 只存在于 GUI i18n）。

风险与对策：

• Models 页拥挤→ 备用方案为独立页面；决策在 A 阶段以截图证据记录，不在 B 阶段重开讨论（最终用户规格直接选择了独立页面方案）；
• i18n 漂移（de 常滞后）→ key-diff 测试使其机械化（最终由tsc -b奇偶校验兜底）。

此外，050 记录了两个与本阶段直接相关的实施偏差，值得读者注意：

1. 路径重命名：规划中的src/anthropic/*实际落地为src/claude/*，避免与既有 provider 适配器 src/adapters/anthropic.ts 冲突，测试文件相应为tests/claude-*.test.ts；
2. 非流式策略：路由适配器拒绝内部stream:false，入站始终以stream:true回放，并通过collectAnthropicMessage将翻译后的 Anthropic SSE 折叠为 JSON 消息给非流式客户端。

八、小结

Phase 3 的落地闭环验证了该功能面的完整性：管理 API 提供配置读写与校验的安全边界，GUI 以"侧边栏即时开关 + 独立配置页"双入口兑现了 D2"不新增独立进程/端口"的集成决策，i18n 编译期奇偶校验与 docs-site 多语言指南保证了功能可被发现、可被理解、可被检索。开发者若想深入本主题，可依次阅读 Phase 3 规划、Phase 1 入站协议、Phase 2 发现与别名、关闭记录，再对照 GUI 页面、管理路由、启动器 与 docs-site 指南 进行源码级验证。