1. Opencode 启动就崩：内置 Bun 段错误到底卡在哪

如果你在 Windows 上用 Opencode 做本地 CLI 开发，某天突然发现：在用户目录敲opencode一切正常，一进项目文件夹就立刻抛出一行Bun v1.3.5 (1e86cebd) Windows x64 (baseline) panic(thread xxxxx): Segmentation fault，然后进程直接没了——这不是你的代码写错了，而是 Opencode 内置的 Bun 运行时在特定目录上下文里初始化失败。Opencode 是一个跑在终端里的 AI 编码助手，它把 Bun 作为内嵌运行时来加速启动和文件扫描，适合习惯命令行、想让 AI 直接读写本地仓库的开发者。问题在于，Bun 1.3.5 这个版本在 Windows 上对「非用户目录」的初始化路径存在缺陷，一旦当前工作目录不是C:\Users\你的用户名，它访问证书存储或解析.bunfig.toml时就可能触发内存访问违规，表现为段错误。

这个故障最迷惑人的地方是「命令本身没坏」：opencode --version能正常打印版本号，opencode upgrade也能跑完，但一进项目目录就崩。很多人第一反应是重装 Opencode，结果升到 1.1.44、1.1.48 依旧报同样的错，因为增量升级并不会替换内嵌的 Bun 运行时，缓存和状态文件也被保留了下来。我实测下来，真正要解决的是两件事：一是把损坏的本地状态和冲突的独立 Bun 清干净，二是把请求链路从默认 endpoint 切到稳定通道，避免启动阶段因为网络初始化再叠加一层崩溃。下面按「先复现、再清理、后切 endpoint、最后验证」的顺序走一遍，每一步都给可复制的命令和配置。

需要先明确一点：段错误属于运行时崩溃，不是请求报错。所以排查时要先把「运行时问题」和「链路问题」分开，否则你会在网络配置上白折腾半天。判断方法很简单——如果错误信息里出现Segmentation fault、panic、thread这类词，优先按运行时处理；如果出现401、ECONNREFUSED、local proxy failed，那才是链路问题。本文聚焦前者，同时把 endpoint 切到 TaoToken 作为收尾的稳定化动作。

2. 前置准备：清理环境并把 endpoint 指向 TaoToken

在动 Opencode 之前，先把环境里的干扰项排掉。第一步是确认有没有独立安装的 Bun，因为它会和 Opencode 内嵌的 Bun 抢 PATH，导致版本错乱。在 PowerShell 里执行：

where.exe bun

如果输出里有C:\Users\你的用户名\.bun\bin\bun.exe这类路径，说明你装过独立 Bun。用 npm 装的可以这样卸：

npm uninstall -g bun

如果是官方脚本装的，用 Bun 自带卸载：

bun uninstall

接着彻底清 Opencode 的状态和缓存。注意opencode uninstall需要命令本身可用，所以要在用户目录下执行，别在项目目录里跑：

cd C:\Users\Administrator opencode uninstall opencode uninstall --purge

--purge会连配置和缓存一起删，这一步很关键，因为段错误往往就是损坏的状态文件在项目目录下被读取时触发的。清完之后用 npm 重装，别再用opencode upgrade：

npm cache clean --force npm install -g opencode-ai opencode --version

到这里运行时环境是干净的。接下来处理 endpoint。Opencode 支持通过环境变量指定模型服务的 Base URL 和 Key，我们把它指向 TaoToken 的 API 地址，这样启动阶段就不会去连默认通道。TaoToken 的 API 入口是https://taotoken.net/api，Key 在控制台的 API Keys 页面生成。先设置环境变量（PowerShell 当前会话）：

$env:OPENAI_BASE_URL = "https://taotoken.net/api" $env:OPENAI_API_KEY = "sk-你的TaoToken密钥"

如果你希望永久生效，用setx：

setx OPENAI_BASE_URL "https://taotoken.net/api" setx OPENAI_API_KEY "sk-你的TaoToken密钥"

注意setx写入后要新开终端才生效。Key 的获取入口在 TaoToken 控制台，登录后进 API Keys 新建即可，地址是https://taotoken.net/console。模型 ID 按你实际要用的填，比如claude-sonnet-4-5或gpt-4o，具体以控制台模型列表为准。这一步做完，Opencode 启动时读到的就是 TaoToken 的 endpoint，而不是默认那条可能触发额外初始化的链路。

3. 可复制配置：settings 与 endpoint 片段

Opencode 的配置分两层：一层是环境变量，一层是项目或全局的配置文件。为了让配置可复现，建议把 endpoint 写进配置文件而不是只靠环境变量。Opencode 读取的全局配置目录在 Windows 下通常是C:\Users\你的用户名\.config\opencode\，项目级配置放在项目根目录的.opencode\下。先建全局配置：

mkdir C:\Users\Administrator\.config\opencode notepad C:\Users\Administrator\.config\opencode\config.json

写入下面这段 JSON，把 Base URL、Key 和 Model ID 三件套都固定下来：

{ "provider": { "taotoken": { "type": "openai", "baseURL": "https://taotoken.net/api", "apiKey": "sk-你的TaoToken密钥", "models": { "claude-sonnet-4-5": { "id": "claude-sonnet-4-5", "name": "Claude Sonnet 4.5" }, "gpt-4o": { "id": "gpt-4o", "name": "GPT-4o" } } } }, "model": "taotoken/claude-sonnet-4-5" }

如果你用的是 TOML 风格的配置（部分版本支持），等价写法是：

[provider.taotoken] type = "openai" baseURL = "https://taotoken.net/api" apiKey = "sk-你的TaoToken密钥" [provider.taotoken.models.claude-sonnet-4-5] id = "claude-sonnet-4-5" name = "Claude Sonnet 4.5" [model] default = "taotoken/claude-sonnet-4-5"

项目级配置可以只覆盖 model，避免每个项目都写 Key：

{ "model": "taotoken/gpt-4o" }

放好配置后，回到项目目录测试。这里有个细节：配置文件里的baseURL结尾不要带/v1，TaoToken 的 API 根就是https://taotoken.net/api，路径拼接由客户端处理。如果你之前填了/v1导致 404，去掉即可。另外 Key 不要提交到 git，把.config\opencode\config.json加进全局 gitignore，或者用环境变量注入。

配置写完后，先别急着跑完整交互，用一条最小请求验证链路是否通。Opencode 本身没有独立的ping命令，但你可以用 curl 直接打 TaoToken 的接口，确认 Key 和 endpoint 没问题：

curl https://taotoken.net/api/v1/models \ -H "Authorization: Bearer sk-你的TaoToken密钥"

返回模型列表就说明链路是通的。这一步能把「运行时崩溃」和「鉴权失败」彻底分开——如果 curl 通、Opencode 崩，那问题一定在 Bun 运行时；如果 curl 就 401，那先解决 Key。

4. 验证请求：重启终端后跑通项目目录

配置就位后，做一次完整的重启验证。先把所有 cmd 和 PowerShell 窗口关掉，确保环境变量和 PATH 重新加载。然后新开一个终端，进项目目录：

cd D:\your-project opencode

如果不再出现Segmentation fault，说明运行时清理生效了。接着在 Opencode 交互界面里发一条最简单的请求，比如让它读一下当前目录的文件列表，观察是否正常返回。成功的话你会看到模型输出，而不是进程直接退出。为了确认 endpoint 真的走了 TaoToken，可以在请求时留意启动日志里的 provider 名称，或者临时把 Key 改错，看是否返回 401——如果返回 401，说明请求确实打到了 TaoToken，链路配置正确。

再补几个场景测试，确保问题不复发：

如果项目目录仍然崩，但用户目录正常，说明还有残留状态没清干净。回到第 2 步，确认opencode uninstall --purge真的执行了，并且检查项目目录下有没有.opencode缓存文件夹，手动删掉再试。另外，VSCode 里的 Opencode 插件也要卸掉，插件可能带着旧版本运行时和命令行版本冲突。卸载路径是扩展面板搜opencode，全部卸载后重启 VSCode。

验证通过后，建议把这次成功的配置备份一份，尤其是config.json。下次换机器或者重装，直接复制过去改 Key 就行，不用再从头排查。

5. 常见报错排查：401、local proxy failed、reading choices

段错误解决后，剩下的多半是链路层报错。下面按真实错误信息对照处理。

401 Unauthorized：Key 无效或没带上。检查OPENAI_API_KEY是否设置成功，PowerShell 里用echo $env:OPENAI_API_KEY看有没有值。如果配置文件和环境变量同时存在，确认优先级——一般环境变量覆盖配置文件。另外确认 Key 没有多余空格，复制时容易带上换行。

local proxy failed / ECONNREFUSED：客户端在连本地代理端口，但代理没起来。这通常是因为之前配过HTTP_PROXY或HTTPS_PROXY环境变量，指向了一个已经关闭的本地端口。清掉这两个变量：

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue

然后确认OPENAI_BASE_URL是https://taotoken.net/api，不要指向127.0.0.1或localhost。

reading choices / unexpected response：客户端解析响应时字段对不上。常见原因是 Base URL 多写了/v1或者少写了路径，导致返回的是 HTML 错误页而不是 JSON。把baseURL统一成https://taotoken.net/api，让客户端自己拼/v1/chat/completions。如果还报错，用第 3 步的 curl 命令确认接口返回的是标准 JSON。

OAuth 相关报错：如果你之前登录过某个 OAuth 通道，配置里可能残留了 token 字段，和 API Key 模式冲突。打开config.json，删掉oauth或token相关字段，只保留apiKey。然后重启终端。

Bun 段错误复发：如果清理后过一段时间又崩，检查是不是又装了独立 Bun，或者opencode upgrade把内嵌运行时换回了有问题的版本。坚持用npm update -g opencode-ai更新，别用自带 upgrade。同时避免在 Opencode 运行时执行git reset --hard这类会删掉它正在读写文件的命令，正确顺序是先退出 Opencode，再跑 git，最后重开。

排查时记住一个原则：先看错误类型，Segmentation fault走运行时清理，401/ECONNREFUSED/choices走链路配置。两条线不要混着调，否则越调越乱。

6. 稳定跑下去：把 endpoint 固定到 TaoToken

段错误这类运行时崩溃，本质是环境不干净加上内嵌运行时缺陷叠加出来的。清理重装能解决当下，但要长期稳定，关键是让启动路径尽量简单、可控。把 endpoint 固定到 TaoToken 之后，Opencode 启动时不再去探测默认通道，少了一层网络初始化，崩溃概率明显下降。你可以把config.json里的 provider 配置当成标准模板，换项目只改 model 字段。

如果你打算长期用 Opencode 做编码和 Agent 任务，建议直接上 Coding Plan，额度和通道更稳，入口在https://taotoken.net/coding-plan。日常调试模型输出、对比不同模型效果，用模型对话页面就够了：https://taotoken.net/chat。Key 的管理和轮换在控制台：https://taotoken.net/console，API Keys 单独页面是https://taotoken.net/api-keys。接入细节和参数说明看文档：https://taotoken.net/doc。如果你同时用 Claude Code，它的接入配置可以参考https://taotoken.net/claude-code。

最后留一个我踩过的坑：清理缓存时别只删 npm 的，Opencode 自己在%APPDATA%和项目目录下也会写状态文件，--purge之外手动检查一遍更保险。配置改完一定要新开终端，环境变量不会在旧窗口里刷新。把这两点做到，段错误基本不会再找上门。