终端 OpenCode 为什么比浏览器更容易「总超时」

OpenCode 常见工作流包括：在 shell 里启动 TUI、执行一次性 run 子命令、或通过内置服务与 模型 API 通信。与桌面浏览器访问文档站点不同，这些请求通常由 node、bun 或独立二进制拉起的子进程发出，它们不保证继承 macOS / Windows 的系统 HTTP 代理。结果就是读者非常熟悉的一幕：网页端一切正常，终端里 OpenCode 却总卡在握手或重试。根因往往不是「模型坏了」，而是命令行根本没有走上你为海外 API 准备的那条 Clash 出站。

另一类高概率问题可以称为半经过代理：模型 API 请求命中了代理节点，但OAuth 授权页、配置发现（例如部分环境下的 .well-known 资源）或静态脚本所在的 CDN 域名仍直连。TLS 状态机、重定向链与静态依赖被拆在两条路径上时，客户端往往会指数退避重试，于是你看到的就是长时间无返回或笼统的API 超时。这与 Cursor 登录与 AI 超时 中强调的「解析路径与路由路径要一致」是同一逻辑，只是 OpenCode 更贴近裸终端 CLI，对分流遗漏更敏感。

ℹ 先做的两个核对：其一，当前 Shell 是否导出 HTTPS_PROXY、ALL_PROXY 指向 Clash 的 mixed-port 或等价 SOCKS 端口，或系统级 TUN 已开启；其二，连接日志里文档域、models.dev 以及你实际选用的云厂商接口主机名是否落在同一策略组。两项缺一，就不必先怀疑节点「慢」。

OAuth 与登录：文档能开不代表 CLI 已闭环

OpenCode 在配置凭据时，常见路径包括命令行驱动的 auth login、浏览器辅助的授权回调，以及写入本机凭据仓库（如用户目录下的共享配置）。串联域名除了直接的 模型 API，往往还包含官方文档与下载页所在的主域（公开资料中常见 open-code.ai、opencode.ai、dev.opencode.ai 等变体，具体以你当前版本与镜像为准）、以及第三方账户与 Models.dev 一类模型目录服务。若规则只写了某一两家云厂商的 API，却漏掉授权回调或发现端点，浏览器窗口会一片空白，终端侧则一直停在「等待登录」——本质是 OAuth 流程在半路上断开，与 CLI 版本号或本地磁盘空间不一定相关。

实务上建议把「文档／发现／平台」与「实际对话所走接口」放进同一可视策略组（示例名 OPencode_AI，可按订阅习惯改写），再用域名分流细则覆盖相邻 CDN。避免为了省事使用过于宽泛的 DOMAIN-KEYWORD 以免误伤无关站点；优先 DOMAIN-SUFFIX 与远程 RULE-SET，并对日志里新冒头的子域做增量增补。企业环境若禁用浏览器 OAuth 或要求固定出口，应先满足单位策略——本文只讨论路由层如何把已知合法主机名对齐。

模型 API、文档站与 CDN：建议如何分组

官方文档与静态资源

排障阶段很多人会反复打开在线文档核对参数，却忽略了 CLI 在运行时也会拉取文档片段、错误页样式或诊断脚本。若这些资源落在与接口不同的 CDN 后缀下，而你的规则只「精细照顾」了 API，表面现象可能是界面渲染停滞或偶发崩溃。做法是把文档主域及其静态依赖与模型请求放在同一策略意图下，并通过订阅里的站点规则集做版本跟随。

Models.dev 与模型清单

公开文档显示 OpenCode 会结合 Models.dev 等目录拉取模型元数据与可用性信息。若清单接口被直连卡住，而对话接口走了代理，用户会感到「能连上模型却不能列举／切换」。因此 models.dev 及其子域应在日志中单独确认命中情况，而不是假设「只配云厂商就够了」。

云厂商与 OpenAI 兼容接口

当你把默认供应商切到某一海外推理平台，或启用 OpenAI 兼容基址时，主机名族会与官网文档完全不同。务必以你在客户端配置里填写的 base URL 为准，把它解析到同一策略组；若还叠加了企业反向代理或区域端点，更要在连接日志里核对真实 SNI，而不是凭记忆抄写旧清单。可对照本站 OpenAI Codex CLI 分流 中关于接口与 CDN 并列的写法，但不要原样照搬域名，只借鉴「同类域名一起收口」的结构化思路。

规则示例：DOMAIN-SUFFIX 与策略组

下面是一段说明性 YAML 片段：策略组名、端口与订阅骨架需按你的环境替换；重点是官方文档域、models.dev、以及你选用的模型 API 后缀并列，国内常见目的地仍可直连。更系统的写法见 规则分流最佳实践。

Illustrative YAML fragment

rules:
  - DOMAIN-SUFFIX,opencode.ai,OPencode_AI
  - DOMAIN-SUFFIX,open-code.ai,OPencode_AI
  - DOMAIN-SUFFIX,dev.opencode.ai,OPencode_AI
  - DOMAIN-SUFFIX,models.dev,OPencode_AI
  - DOMAIN-SUFFIX,api.openai.com,OPencode_AI
  - GEOIP,CN,DIRECT
  - MATCH,DIRECT

实际环境中官方域名可能合并或新增子域；api.openai.com 仅在你真正使用该兼容端点时才有意义。请以复现时日志里的主机名为准迭代规则，而不是维持一份永远过期的静态列表。MATCH 若默认 直连，任何尚未收录的新后缀都会悄悄失败，对外仍报告API 超时。TLS 错配时可结合 从日志读懂 timeout 与 TLS 分段分析。

终端环境变量与 TUN：两条闭环路径

环境变量路线适合「只在当前终端会话里跑 OpenCode」：为 Clash 打开 mixed-port，在 ~/.zshrc 或项目专用 shell 配置里导出 export HTTPS_PROXY=http://127.0.0.1:7890（端口按实），按需补 ALL_PROXY 与细粒度 NO_PROXY（排除局域网、容器桥接与公司内网域名）。具体端口写法可与 Docker 与终端 mixed-port 一文对齐。

TUN 路线适合「多种语言运行时混杂、环境变量难以全覆盖」：由操作系统在三层转发，未自觉遵循代理字段的程序同样进入 Clash 的分流决策。代价是与单位 VPN、虚拟机桥接、部分游戏反作弊驱动可能冲突，实施前建议阅读 TUN 模式深度解析。两条路线择一为主，避免同机堆叠多套改路由工具却缺乏统一日志。

DNS、fake-ip 与规则顺序

即便域名分流写得漂亮，DNS 抢答、fake-ip 过滤遗漏或嗅探配置不当仍可能让终端 CLI 解析到「看起来合法、却与真实路由不一致」的地址。要记住：解析路径不等于最终路由路径。应在 Clash 内统一 DNS 出口，并在日志中核对「域名 → 策略组 → 实际 outbound」是否闭环。规则顺序上，国内业务与局域网直连通常靠前；细分到 OpenCode、模型 API 与CDN 的业务规则紧随其后；过宽的拦截或广告类规则若排在前面，可能无声吞掉 OAuth 回调。

若系统 DoH、路由器 DNS 与 Clash 内置 DNS 同时存在，容易出现「浏览器问一套解析器、CLI 问另一套」的分裂。排障时临时收敛到单一解析路径，更容易对照现象。常见问题 中关于 DNS 的条目可作为补充读物。

MCP 与多供应商：每加一类服务就多一组主机名

OpenCode 对 MCP 与多工具链的支持意味着：你在配置里每增加一个远程端点或AI 编程代理插件，就等于增加了一组尚未被旧规则覆盖的主机名。若只有主会话域名走了代理，而 MCP 的 WebSocket 或 HTTPS 入口仍直连，症状往往表现为某个子命令随机失败、或仅在启用特定工具时API 超时。建议把新增集成单独跑一次连接日志采集，再把主机名合并进 OPencode_AI 或与之等价的策略分组，而不是赌 MATCH 能蒙对。

连接日志：把 timeout 还原成漏域名还是错出口

复现场景时建议固定记录三件事：时间戳、失败时的主机名、以及命中的规则名。若日志显示 模型 API 已走代理，但 models.dev 或文档 CDN 仍直连，应优先修正域名分流；若全部命中代理却仍超时，再评估节点质量、UDP、链路 MTU、系统时钟漂移或上游服务状态。若同一终端还在跑 npm、cargo 安装依赖而失败，要区分「模型请求」与「包仓库下载」——后者常指向 registry.npmjs.org 等域名，需要单独规则，以免误判为 OpenCode 自身故障。

与 Codex CLI、Gemini CLI 分流有什么不一样

本站已有 OpenAI Codex CLI 与 Gemini CLI 的分流长文；它们分别锚定 OpenAI 账户体系与 Google AI 域名族。 OpenCode 作为相对独立的终端代理框架，往往同时触及自研文档域、Models.dev、以及你手动挑选的多项 模型 API ——主机名集合是「拼盘」而非单一云。你可以共用同一台 Clash，但不要假设「Gemini 规则写好了，OpenCode 就会自动好」。正确做法是以 OpenCode 实际复现日志为准维护一份独立后缀表，并在升级 CLI 或更换供应商时复查。

常见问题（正文精炼版）

临时开全局代理能绕过吗？短期排障可以，但会抬高整体延迟与触发风控的概率；长期仍应回到可读分流与日志验证。

登录成功却仍拉不下模型列表怎么办？回到 Models.dev 与文档域是否同事走 OPencode_AI；再看 DNS 是否分裂；最后确认上游目录服务可用。

Windows 与 Linux 差异大吗？差异主要在环境变量继承、防火墙放行与 TUN 驱动栈；核心检查仍是「终端是否经过 Clash」与「相关后缀是否对齐」。

⚠ 合规提示：请遵守所在地法律法规与各模型供应商、文档站的服务条款。本文仅描述在有权使用的网络前提下如何校准路由与 DNS，不鼓励未授权访问、绕过组织策略或任何违法行为。

自检清单

  1. 确认有权在当前环境使用 Clash 与所选 模型 API。
  2. 核对终端是否通过环境变量或 TUN 经过本机 Clash。
  3. 在日志中检查文档域、models.dev、OAuth 相关主机与接口域名是否命中同一策略组。
  4. 审视规则顺序：国内直连、局域网、业务细分、MATCH。
  5. 验证 DNS、fake-ip、嗅探是否引入解析与路由分裂。
  6. 确认订阅与远程规则集更新通道未被错误环路代理阻断。
  7. 区分 CLI 模型流量与包管理器下载域名，避免误判。
  8. 本地因素排除后，再评估节点质量与上游状态页。

结语

OpenCode 在终端里报API 超时，多数可以先还原成两件事：CLI 进程没有真正接入 Clash，以及模型 API、OAuth、Models.dev 与CDN 静态域没有在同一个分流意图下闭环。相比只在浏览器里问「文档能打开吗」，终端 CLI 场景更依赖你把实际主机名写进可读规则，并用连接日志反复校验，而不是反复重装运行时。

市面上不少「一键全局」类代理工具或家用固件上手快，却很难把命中详情讲清楚；一旦出现间歇性超时，用户往往只能重启设备碰运气。Clash 系的可编程规则、策略组与实时日志能把症状落到具体域名与出口；在同品类中，Clash V.CORE 在兼容现代内核与远程规则集的前提下，对桌面用户足够友好，更适合长期维护一份针对 OpenCode 与多供应商 模型 API 的域名分流矩阵。

→ 立即免费下载 Clash，开启流畅上网新体验，让终端里的 OpenCode 在 OAuth、CDN 与推理接口之间走出一条稳定、可复查的路径，而不是把一切交给盲目重试。