1. 从一次启动失败说起bootstrap 到底在做什么你敲下opencode run 帮我重构这个函数终端闪了两下然后报出一行local proxy failed或者干脆卡在bootstrapping不动。这时候你打开源码想看看它到底干了什么结果发现启动链路散在七八个文件里每个文件都不长但拼起来就是一条从「用户敲命令」到「Agent 可工作」的完整流水线。这就是 bootstrap 源码解析要解决的问题。bootstrap 不是一件事而是三层职责的叠加第一层把当前目录变成 InstanceContext第二层让运行时真正就绪配置 插件 后台服务第三层把上下文传播给所有下游代码。任何一层出问题Agent 都无法正常工作。我试过在本地反复打断点跟这条链路发现最容易踩坑的地方不是逻辑复杂而是顺序敏感——配置必须在插件之前插件必须在后台服务之前而这三个又都必须在 Agent Loop 启动之前。顺序错了报错信息往往指向一个完全无关的地方比如你以为是网络问题其实是插件改了配置但服务已经用旧配置初始化完了。这篇文章会带你逐层拆开这条链路先看 CLI 入口怎么包裹生命周期再看store.load内部怎么构建上下文然后是config.get、plugin.init、六个后台服务的并发初始化最后给出可复制的调试配置和断点验证步骤。适合已经能跑起来 opencode、但想搞清楚启动阶段到底发生了什么的人也适合正在设计自己 CLI 工具启动流程的开发者。核心检索词先明确bootstrap 源码解析、环境检测、运行时初始化、启动链路。这四个词贯穿全文你可以在每一层里找到对应的代码位置和验证方法。2. 环境检测与上下文构建InstanceStore.load 内部做了什么2.1 effectCmd 的三层生命周期包裹每条需要项目上下文的命令入口层都会自动包裹一个三层生命周期。简化后的代码大概是这样// 简化自 packages/opencode/src/cli/effect-cmd.ts:87-94 const { store, ctx } await AppRuntime.runPromise( InstanceStore.Service.use((store) store.load({ directory }).pipe( Effect.map((ctx) ({ store, ctx })) ) ), ) try { await AppRuntime.runPromise( opts.handler(args).pipe(Effect.provideService(InstanceRef, ctx)) ) } finally { await AppRuntime.runPromise(store.dispose(ctx)) }这段代码的意义在于handler 被写成一个纯 Effect不需要知道 Instance 什么时候加载、什么时候释放。框架替你覆盖了三种退出路径——正常 return、抛出异常、Effect 中断——全部命中finally。为什么这件事值得单独提因为如果每条命令自己管理 init/dispose两条命令之间就可能出现「前一条泄漏了监听器后一条工作不正常」的问题。用三十行代码把这个隐患从二十多条命令中一次性清除是启动链路设计里性价比很高的一步。这层封装的代价是你必须理解AppRuntime.runPromise是一个必要的桥接——Promise 世界和 Effect 世界之间的通道。InstanceStore.Service.use()拿到 storestore.load()跑出 ctxEffect.provideService把 ctx 注入到 handler 的 Effect 环境中。每一层都是精确设计的取舍。2.2 InstanceRuntime 桥接层的设计取舍内部有两种调用风格一种是在 Effect 运行时内Layer.effect、Effect.gen可以直接yield*获取服务另一种是传统 async/await 代码CLI handler、测试文件它们无法 yield Effect。InstanceRuntime 就是为后者准备的桥接层// packages/opencode/src/project/instance-runtime.ts:9-11 export const load (input: LoadInput) AppRuntime.runPromise( InstanceStore.Service.use((store) store.load(input)) ) export const disposeInstance (ctx: InstanceContext) AppRuntime.runPromise( InstanceStore.Service.use((store) store.dispose(ctx)) )这里的模式是「借 Effect 的能力还 Promise 的接口」。AppRuntime.runPromise是全局 Effect 运行时的唯一入口——它创建了一个 Effect.Runner把 Effect 跑完再转成 Promise。naive 方案可能直接把 Effect 的能力暴露给调用方yield* store.load()但这意味着调用方也必须运行在 Effect 上下文中。而 CLI handler 的入口来自 yargs——yargs 是纯 async/await 的。所以必须在 CLI 边界做一次转换。2.3 boot 内部从目录到 InstanceContextInstanceStore.boot()的第一步是project.fromDirectory(directory)// packages/opencode/src/project/instance-store.ts:45-63 const boot (input: LoadInput { directory: string }) Effect.gen(function* () { const ctx: InstanceContext input.project input.worktree ? { directory: input.directory, worktree: input.worktree, project: input.project, } : yield* project.fromDirectory(input.directory).pipe( Effect.map((result) ({ directory: input.directory, worktree: result.sandbox, project: result.project, })), ) yield* bootstrap.run.pipe(Effect.provideService(InstanceRef, ctx)) return ctx })构建 InstanceContext 有两种路径热路径input 已含 project worktree跳过fromDirectory直接构造冷路径大部分情况调用project.fromDirectory(directory)发现项目。fromDirectory内部调用了projectV2.resolve()去解析目录检测是否在 git 仓库内、获取 worktree 路径、计算出 project ID。然后 upsert 到 SQLite 数据库更新 sandboxes 列表最后发射project.updated事件。这个过程之所以存在是因为需要知道「当前目录对应哪个项目」——同一个 git 仓库的不同子目录启动project ID 必须一致不同仓库之间project ID 必须不同。没有fromDirectory每个目录就是一个独立的项目多个子目录之间的 session、权限、配置就无法共享。2.4 环境检测的调试配置如果你想在本地复现这条链路可以在项目根目录放一个调试配置// .opencode/debug.jsonc { logLevel: debug, bootstrap: { trace: true, breakOn: [config.get, plugin.init, service.init] }, instance: { cache: false, verbose: true } }然后在instance-store.ts的boot函数入口打断点观察input.directory和input.project的值。第一次启动时input.project是 undefined走冷路径第二次启动同一目录时如果缓存命中会走热路径。你可以通过对比两次的调用栈来确认缓存是否生效。3. 运行时初始化config.get 与 plugin.init 的可复制配置3.1 config.get 的第一道关卡InstanceContext 构建完成后bootstrap.run调用config.get()// packages/opencode/src/project/bootstrap.ts:32-36 const run Effect.gen(function* () { const ctx yield* InstanceState.context yield* Effect.logInfo(bootstrapping, { directory: ctx.directory }) yield* config.get() // 第一步配置加载 yield* plugin.init() // 第二步插件初始化可改配置 // ... 6 个服务并发 })config.get()返回的是Effect.EffectInfo这意味着它不会在 get 时重新读文件——配置的解析和合并已经在 Service 初始化时完成了。这个设计有一个重要的隐藏含义配置加载是 eager 的但不会随着每次 get 重复。naive 方案可能每次 get 都重新读文件确保配置最新——但这里选择了「一旦就绪就不变」的契约。原因在于配置影响了太多下游状态Agent 列表、provider 凭证、权限规则如果配置在运行中突然变化Agent 的行为会变得不可预测。配置热更新是通过专门的控制通道实现的不是自动重读。Config.Interface 定义了六个方法get()获取当前项目配置、getGlobal()获取全局配置、update()/updateGlobal()写入配置、invalidate()显式让缓存失效、directories()配置源目录列表。配置合并是多层叠加全局~/.config/opencode/opencode.jsonc→ 项目级./opencode.jsonc→ 环境变量覆盖。mergeConfigConcatArrays确保数组字段如 instructions是拼接而非替换。3.2 可复制的 settings 片段如果你要接入自己的模型服务配置文件里最关键的三件套是 Base URL、Key、Model ID。以 TaoToken 为例配置片段如下// ~/.config/opencode/opencode.jsonc { provider: { taotoken: { baseURL: https://taotoken.net/api, apiKey: sk-your-key-here, models: { claude-sonnet: { id: claude-sonnet-4-20250514, name: Claude Sonnet } } } }, model: taotoken/claude-sonnet }注意baseURL用的是https://taotoken.net/api不带任何额外路径。Key 从控制台生成后直接填入不要加引号以外的字符。Model ID 必须和 provider 支持的列表一致写错了会在config.get阶段就报错而不是等到请求时才失败。3.3 plugin.init 为什么必须在 config 之后回头看bootstrap.run的顺序插件必须在其他服务之前初始化原因只有一个插件可以修改配置。插件系统里有一类特殊的 ConfigPlugin。这类插件的初始化动作可能包括从远程拉取配置模板、注入自定义的 Agent 定义、修改权限规则。如果先初始化了 LSP 或 VCS 服务它们依赖于完整的配置插件修改配置后这些服务可能工作在不一致的配置上——出现「LSP 用了旧的 provider 配置但 Agent 用了新配置」的问题。naive 方案可能会说那把配置做成响应式的服务监听配置变更不就行了但问题是配置变更不是增量事件驱动的——插件 init 是一个同步操作在它完成之前配置是不完整的。你在「配置一半」的状态下启动其他服务这就跟汽车还没装好轮子就点火一样——也许走得动但出问题的概率很高。另一个方案是「所有服务都支持热重载配置变了就重新 init」。这里没有走这条路原因有二复杂性代价每个服务都需要实现配置变更监听、状态迁移、rollback六个服务乘以三个状态约十八个复杂度单元实际需求配置在 bootstrap 阶段之后极少变更为极低频场景增加永久复杂度不划算。所以选了最简单直接的方案——先 config、再 plugin、最后其他服务。一条直线没有状态跃迁。3.4 插件加载的三阶段管线plugin.init()内部做三件事从配置中读取 plugin 字段plugin spec 列表对每个 spec做 resolve → 按 kindserver/tui识别 entrypoint → 动态 import加载成功后在 registry 中注册。它的复杂度不在加载本身而在降级策略某个插件 resolve 失败时是跳过、重试、还是终止整个 bootstrap插件加载器在packages/opencode/src/plugin/loader.ts中定义了完整的三阶段管线resolve定位 target 检测 entrypoint 兼容性检查→ load动态 import→ finish注册到运行时。如果 resolve 失败比如 npm 包未安装——属于 install 阶段错误且是 file-plugin 时会在wait()之后重试一次其他阶段的失败永久跳过。选择是「跳过但记录」。plugin.init()不会因为某个插件加载失败就阻止 Agent 启动——但如果插件是 config plugin可以在 load 过程中修改配置跳过它的后果可能已经影响到配置完整性。所以 config plugin 的加载其实是惰性且安全的它们的影响通过 Effect 的forkIn(scope)隔离在自己的 Effect 沙箱中。4. 启动链路验证六个服务并发初始化与成功结果4.1 并发 init 的意图yield* Effect.forEach( [lsp, shareNext, format, vcs, snapshot, project], (s) s.init().pipe( Effect.catchCause((cause) Effect.logWarning(init failed, { cause }) ) ), { concurrency: unbounded, discard: true }, )六个服务分别是LSP 语言服务器协议客户端提供代码补全和诊断能力ShareNext 分享与协作功能Format 代码格式化Vcs 版本控制集成Snapshot 快照管理用于安全回退Project 项目元数据管理订阅/init命令。这些服务有一个共同点它们对 Agent 不是立即可用的。用户输入问题后的第一反应LLM 调用、工具执行不需要它们。因此它们被设计为后台惰性初始化——即使某个服务 init 失败走catchCause→logWarningAgent 仍然可以工作。naive 方案可能把所有服务串行 init——保证顺序确定好调试。但代价是用户在opencode run之后要等 LSP 启动 → VCS 扫描 → Format 加载 → Project 注册全跑完才看到提示符。这里选择了「容错并发」——每个服务自己管理生命周期通过Effect.forkScoped在 per-instance scope 内启动bootstrap.run只负责 await 它们第一次具体化。4.2 容错的心态注意catchCause而不是catchTag——它捕获所有类型的失败不管是可以恢复的配置缺失还是不可恢复的数据库错误。这看起来有点粗放但意图明确bootstrap 的目标是让 InstanceContext 可工作不是完美。LSP 挂了你仍然可以写代码提问。Snapshot 挂了顶多是无法回退到上一个安全检查点。六个服务中任意一个失败走catchCause→logWarning不影响其他服务的 init 结果。三个服务的 init 路径汇总到同一个 DONE 状态——Agent 可以带着「部分服务缺失」继续工作。naive 方案可能会让任何一个服务的失败阻断整个 bootstrap比如抛出异常终止但这里选择了「能用比完美更重要」的哲学。每个服务的init()内部也遵循类似的容错策略。比如Project.init()只是通过InstanceState.get(initState)等待范围订阅就绪// packages/opencode/src/project/project.ts:427-429 const init Effect.fn(Project.init)(function* () { yield* InstanceState.get(initState) })它只是 await 了一个缓存的 Effect——实际的订阅创建在InstanceStore.boot()之前的InstanceState.make()中就已经完成了。这意味着 init 不会失败因为它只是「等一个已经启动的协程」。4.3 验证请求与成功结果配置好之后用一条最小请求验证整条链路是否打通# 设置环境变量临时验证用 export OPENCODE_PROVIDERtaotoken export OPENCODE_MODELclaude-sonnet # 发起一次最小请求 opencode run 回复 OK 两个字母即可 --debug成功时你会看到类似输出[bootstrap] directory/Users/you/project [bootstrap] config loaded: providertaotoken modelclaude-sonnet [bootstrap] plugin init: 0 plugins loaded [bootstrap] services: lspready vcsready formatready [agent] response: OK如果卡在bootstrapping不动说明config.get或plugin.init阶段有问题。如果看到services: lspfailed但 Agent 仍然返回了结果说明容错机制生效了——LSP 失败不影响核心对话能力。4.4 用断点验证启动顺序在 VS Code 里配置 launch.json把断点打在三个关键位置{ version: 0.2.0, configurations: [ { name: Debug Bootstrap, type: node, request: launch, program: ${workspaceFolder}/packages/opencode/src/cli/index.ts, args: [run, test], console: integratedTerminal, env: { OPENCODE_LOG_LEVEL: debug } } ] }断点位置一instance-store.ts的boot函数入口观察input.directory和input.project。断点位置二bootstrap.ts的run函数内config.get()调用处观察配置是否已加载。断点位置三plugin.init()调用处观察插件列表是否为空。按 F5 启动后你会看到调用栈从effect-cmd.ts→instance-runtime.ts→instance-store.ts→bootstrap.ts逐层深入。每一步的变量值都能在调试面板里看到这比读源码快得多。5. 本篇常见错排查401、local proxy failed 与 reading choices5.1 401 Unauthorized最常见的报错。原因通常是 Key 没填对或者 Base URL 写错了。检查你的配置文件{ provider: { taotoken: { baseURL: https://taotoken.net/api, apiKey: sk-xxxxxxxx } } }注意baseURL末尾不要加/v1或其他路径。Key 必须从控制台复制完整不要手动截断。如果确认配置无误但仍然 401用 curl 直接测一下curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-xxxxxxxx \ -H Content-Type: application/json \ -d {model:claude-sonnet-4-20250514,messages:[{role:user,content:hi}]}如果 curl 也返回 401说明 Key 本身有问题去控制台重新生成一个。如果 curl 成功但 opencode 报 401说明配置文件没被正确加载——检查config.get()的日志输出确认它读的是你修改的那个文件。5.2 local proxy failed这个报错通常出现在启动阶段原因是AppRuntime.runPromise在桥接 Effect 和 Promise 时超时或中断。排查步骤先确认没有多个 opencode 进程同时运行ps aux | grep opencode然后检查~/.config/opencode/目录权限是否正确。如果最近改过配置文件尝试删除缓存目录~/.cache/opencode/后重启。另一个常见原因是插件加载卡住。在配置里临时禁用所有插件{ plugin: [] }如果禁用后能正常启动说明某个插件在 init 阶段阻塞了。逐个启用插件定位到具体是哪一个。5.3 reading choices 报错这个报错说明请求已经发出去了但响应格式不符合预期。通常是因为 Model ID 写错了或者 provider 返回了非标准格式。检查你的 Model ID 是否和 provider 支持的列表一致。以 TaoToken 为例Model ID 应该是claude-sonnet-4-20250514这样的完整标识而不是简写。如果 Model ID 确认无误检查请求的max_tokens参数是否过大。某些 provider 对max_tokens有上限限制超过后会返回错误格式的响应。把max_tokens调到 4096 以下再试。5.4 OAuth 相关报错如果你用的是需要 OAuth 的 provider报错通常出现在 token 刷新阶段。检查~/.config/opencode/auth.json是否存在且格式正确{ taotoken: { type: oauth, access_token: your-access-token, refresh_token: your-refresh-token, expires_at: 1735689600 } }如果expires_at已经过期需要重新走一遍授权流程。注意auth.json的权限应该是 600其他用户不可读。5.5 配置不生效改了配置文件但启动后行为没变最常见的原因是配置文件路径不对。config.get()的查找顺序是项目级./opencode.jsonc→ 全局~/.config/opencode/opencode.jsonc→ 环境变量。如果你改的是全局配置但项目目录下也有一个opencode.jsonc项目级的会覆盖全局的。用opencode config show命令可以打印当前生效的完整配置确认你改的字段确实被加载了。如果字段没出现说明配置文件路径不对或者 JSON 格式有语法错误。6. 从启动链路到实际编码把 bootstrap 用起来搞清楚了 bootstrap 的三层职责你在实际使用中就能更快定位问题。启动阶段报错优先检查配置文件和插件运行阶段报错优先检查模型 ID 和网络请求。这两类问题的排查路径完全不同混在一起查会浪费很多时间。如果你打算长期用这套工具做编码和 Agent 任务建议把配置固化下来而不是每次用环境变量临时指定。配置文件放在项目根目录的.opencode/下跟着 git 一起提交团队里每个人都能用同一套配置。Key 这种敏感信息放在全局配置或者环境变量里不要提交到仓库。对于需要频繁切换模型和 provider 的场景可以用 Coding Plan 来管理多套配置。它支持保存多组 Base URL Key Model ID 的组合切换时不用手动改配置文件。配置入口在控制台的 Coding Plan 页面创建好之后在 opencode 里用--profile参数指定即可。验证模型是否正常工作最直接的方式是用模型对话页面发一条测试消息。如果那边能正常返回说明 Key 和 Base URL 没问题问题出在 opencode 的配置加载环节。如果那边也报错说明是账号或额度的问题需要去控制台检查。接入文档里有完整的配置示例和常见问题列表遇到报错可以先对照文档排查一遍。API Keys 页面用来生成和管理 Key注意每个 Key 的权限范围不要用管理员 Key 跑日常任务。启动链路这条线从effectCmd的生命周期包裹到InstanceStore.load的上下文构建再到config.get→plugin.init→ 六服务并发的运行时初始化每一层都有明确的职责边界。理解了这条链路你不仅能更快定位启动问题也能在自己设计 CLI 工具时少踩一些顺序敏感的坑。