前阵子把OpenCode拉下来跑通之后我顺手做了个一般人不太会做的事把它的源码从头到尾读了一遍。原因很简单——用的时候它表现很聪明但一旦涉及它到底是怎么做到的文档里很多东西语焉不详。比如Skills为什么能自动触发LSP信息是怎么喂给模型的this model is not available in your country到底是OpenCode的问题还是上游的问题。与其去issue里翻二手答案不如直接把源码打开看一眼。这篇文章就是那轮源码阅读的笔记整理。它是一篇源码解析不是OpenCode的新手教程但我尽量把社区里问得最多的安装、配置、报错问题也带进去因为很多问题的根因恰好就藏在源码里。适合已经在用或者准备深入OpenCode的开发者也适合对AI编码Agent内部机制感兴趣的读者。1. 先别急着看代码OpenCode的定位和源码仓库结构1.1 它不是聊天工具是一个Agent运行时很多人第一次打开OpenCode觉得它是个带界面的ChatGPT。这个印象不准确。OpenCode的核心不是聊天而是在代码仓库里自主执行任务。它背后是SST团队开源的一个AI编码Agent整个运行时的设计目标就是让模型能够观察代码、修改文件、执行命令、调用浏览器并且在多轮工具调用中保持状态。从这个角度理解读它的源码更像在读一个轻量级Agent框架而不是在读一个聊天软件。这也解释了为什么它的模块会分成工具、模型适配、Skill、LSP、浏览器自动化这么几大块。聊天只需要模型API但Agent需要工具系统、上下文管理系统、权限系统和可扩展的接入层。你很难在一款闭源产品里看到这么完整的分层这恰巧是OpenCode很适合做源码解析的原因。1.2 从入口到核心模块源码目录怎么读源码阅读的第一步是把仓库拉到本地。日常使用OpenCode时官方提供了CLI下载方式桌面版和IDE插件比如VSCode、JetBrains也有对应安装包但读源码需要直接clone仓库。拉到后你会发现核心代码是TypeScript写的安装依赖用的是Bun。从功能上分核心代码大致可以切成这么几块TUI界面层负责终端交互、渲染会话、处理输入输出。会话层记录对话历史、管理上下文窗口、处理附加文件。Agent编排层核心决策循环负责调用模型、解析工具调用、执行工具、回填结果。工具层所有工具的注册、参数校验和执行。模型适配层对接Anthropic、OpenAI、OpenRouter、Ollama等服务商。Skill层技能的发现、加载、匹配与执行。LSP层启动语言服务器把语义信息转成模型上下文。浏览器自动化层封装浏览器动作让Agent能真实操作页面。我读源码建议的顺序是先看会话层和Agent编排层理解一次对话怎么流转然后看工具层和模型适配层理解能力从哪来最后看Skill、LSP、浏览器自动化这些增强模块理解它为什么比普通聊天更懂代码。这个顺序是我自己翻了两次源码后总结的能最快建立全局观。不同版本的目录结构会有差异比如2.x比0.x多了桌面端相关代码但大的分层思路基本延续。1.3 为什么选Bun和TypeScript技术选型也值得聊一句。OpenCode选择Bun作为运行时核心原因是性能——终端工具对启动速度和文件IO有很高要求Bun的启动速度和内置工具链让整个CLI的体感响应很快。TypeScript则给这种复杂状态机提供了约束消息、工具参数、Provider返回值都有明确类型读代码时能省很多脑力。如果你打算自己改源码本地Bun版本最好和仓库要求对齐版本不对会在构建阶段报各种奇怪错误这是第一个容易踩的坑。2. Agent主循环一次让AI改代码的请求在内部走了哪几步2.1 从用户输入到工具调用的完整链路这是全文最关键的一段。一次看似普通的把这段代码重构一下背后OpenCode内部的流转是这样的用户输入进入会话层作为user消息追加到消息列表。Agent层把系统提示词、历史消息、当前上下文里的文件内容、所有已注册工具的定义一起打包成一个模型请求。模型返回结果可能是纯文本也可能包含一个或多个工具调用。如果有工具调用Agent不会直接把它交给用户而是先做参数校验和权限检查再调用对应的工具执行函数。工具返回结果被包装成tool消息追加回消息列表。Agent拿着更新后的历史继续请求模型。反复执行3到6步直到模型不再产生新的工具调用最终回复才展示给用户。这就像你让一个实习生干活他不是一口气给你答案而是查资料→给你看→你反馈→再查→再给你看。OpenCode的Agent循环就是把这个实习生写成了代码。模型能不能完成任务很大程度取决于这个循环设计得好不好。2.2 工具调用与结果回流是整个Agent的发动机工具调用这块从源码上看核心可以用下面的类型来理解interface ToolCall { id: string; name: string; arguments: Recordstring, unknown; } interface ToolResult { ok: boolean; data: unknown; error?: string; }消息列表是Agent的记忆每轮工具调用和工具结果都会被完整记录。这样模型在下一次生成时能够看到我调用了read_file读到了xxx内容从而基于真实文件内容做判断。这也是为什么OpenCode改代码时不会凭空乱改——它的上下文里确实有文件内容。源码里的循环逻辑并不复杂本质上就是一个while循环关键在退出条件只有模型不再请求工具时循环才停止。这个设计直接决定了Agent的自主程度。提示如果你在源码里看到某个工具一直没被模型调用先检查工具定义里的description写得是否清楚。模型是靠description决定要不要调用工具的工具名和参数说明写得模棱两可它就不会用。2.3 导入一段代码进行修改在源码上是如何实现的很多网友问opencode怎么导入一段程序代码并进行修改完善。其实在源码里这个动作并不神秘会话层支持把一个或多个文件作为附加上下文注入。注入后文件内容会以明确的分隔格式出现在消息列表里模型的后续回答就有了具体依据。实际操作时你可以在会话里添加文件也可以直接把文件路径拖进输入框让Agent读取后再修改。比起笼统地说帮我优化一下带上文件后模型的输出完全是两个级别。从源码视角看这里最值得关注的是上下文截断策略——文件内容过长时会话层会怎么裁剪这决定了Agent在大仓库里的可用性。3. 模型适配层invalid api key、地区限制、免费模型是同一件事的三面3.1 Provider抽象OpenCode是怎么统一各家模型API的不同模型服务商的API格式、认证方式、流式协议都不一样。OpenCode在源码里做了一层Provider抽象把各家差异挡住。每个Provider都要实现统一的接口发请求、解析流式输出、转成内部Message和ToolCall。对上层Agent来说它根本不关心模型来自Anthropic还是Ollama它只跟统一的抽象打交道。这也带来了一个非常实际的好处你在一个OpenCode会话里可以随时切换模型服务商甚至可以把同一个问题分别发给Claude和本地模型对比答案。切换模型时会话历史是共享的模型适配层负责把相同的历史翻译成不同服务商能理解的格式。源码里各Provider的差异主要集中在请求体构造和流式解析这两块前者各家格式不同后者大多走SSE但要处理的事件字段不一样。3.2 API key到底从哪来环境变量、配置文件和ccswitchinvalid api key是最常见的问题。源码里API key的读取顺序大致是当前目录配置文件、全局配置文件、环境变量。对于大多数Provider最终靠的还是环境变量常见变量名如下模型服务商常见环境变量AnthropicANTHROPIC_API_KEYOpenAIOPENAI_API_KEYOpenRouterOPENROUTER_API_KEYGoogle GeminiGEMINI_API_KEYOllama不需要key本地服务如果你报invalid api key先按这个顺序查环境变量有没有设置、设置的是不是当前选择Provider对应的变量、key有没有多余的空格或换行、key本身是否过期。社区里常见的ccswitch本质上就是把不同服务商的key集中管理在启动opencode前把当前要用的key注入环境变量。它不干预OpenCode内部逻辑所以排查时记得先确认ccswitch注入之后环境变量里真实的值是什么。另外Linux下经常要手动修改JSON配置文件改完注意JSON格式不能有语法错误一个多余的逗号就会让配置加载失败。3.3 this model is not available in your country是谁报的错这个问题在热搜里出现频率很高。可以明确地说这不是OpenCode源码报的错OpenCode不会自己判断你所在的国家它也没有任何地理探测逻辑。这个错误是模型服务商在服务端返回的OpenCode的请求层只是把Provider返回的错误信息原样透传显示在界面上。从源码角度看这个问题发生在模型适配层请求发出后服务商返回了一个错误响应适配层解析错误体把里面的message字段透传出来。所以你不需要去改OpenCode源码更不应该去搜索任何绕过方案。正确合法的做法是换一个在你当前区域可用的模型服务商或者改用OpenRouter这类聚合平台上的可用模型也可以直接用本地模型比如Ollama彻底绕开服务商区域校验的问题。提示当报错信息带有一段请访问我们的支持页之类的文案时基本可以断定是上游服务商的业务限制不是配置错误也不是OpenCode的Bug。3.4 免费模型和本地模型的接入配置说回opencode免费模型。完全免费使用的方案里我实际用过两种一种是OpenRouter上的免费模型另一种是本地Ollama。OpenRouter的好处是它的API格式兼容OpenAI绝大部分Provider适配成本很低。配置上可以这样理解你在opencode.json的provider里指定自定义的base_url和模型id把OpenRouter或者本地Ollama的服务地址填进去。下面是一个本地Ollama的配置思路示意具体字段名以你所用版本为准{ provider: { ollama: { base_url: http://localhost:11434, models: [qwen2.5-coder:7b] } } }本地模型虽然响应速度取决于机器配置但优点是私密性强、没有区域和配额限制适合用来跑一些敏感代码。如果你在意opencode go套餐的响应速度这类问题我的经验是响应速度的根源在模型服务商和网络链路不在OpenCode这个壳。用同一个Provider和同一个模型换任何客户端速度都差不多。与其纠结工具不如从模型本身和网络质量去解决。4. 读懂代码的两种能力Skills与LSP的源码实现4.1 Skills为什么模型会在需要的时候突然学会新技能Skills在OpenCode里是一组可复用的能力包。一个Skill通常包含一段指令文本告诉模型在什么场景下应该做什么、按什么步骤做可以附带脚本作为辅助工具。源码层面的Skill系统大概由三部分组成加载器负责扫描内置和用户目录下的所有Skill匹配器根据当前任务和Skill的描述判断是否值得使用执行器在模型决定使用Skill后把Skill内容注入上下文并运行关联脚本。很多用户问Skill为什么不生效最常见原因是描述写得不够具体。模型是依靠描述来决定何时使用Skill的如果描述含糊比如处理代码它就无法判断该在什么时候用。正确的描述应该明确触发场景例如当用户要求进行前端可访问性审查时使用。源码里匹配器的逻辑其实很简单没有复杂的语义匹配本质上是把描述和当前对话关键词做一次相关性判断所以描述质量直接决定Skill的可用性。4.2 LSP语义信息是怎么喂给模型的LSP是OpenCode另一个重要的上下文来源。说得直白一点模型本身是看不到你工程里的类型定义、函数引用、报错诊断的。LSP的职责就是把语言服务器提供的语义信息整理成模型能读懂的文本片段在合适的时候注入消息上下文。比如Agent要修改一个函数可以先通过LSP拿到该函数的定义位置、所有调用点、当前工作区里的诊断报错这些信息作为工具结果回填给模型让修改更精准。这种设计非常聪明它没有重新发明一套代码分析器而是复用了编辑器生态里最成熟的Language Server。这意味着OpenCode支持的编程语言广度基本等于社区语言服务器的广度。源码里LSP客户端的启动、初始化、请求挂钩、结果格式化都做得比较独立读这一块时不需关注具体语言关注协议交互就行。如果你在自己的工具里也想集成类似能力直接参考LSP层的设计即可。4.3 一个可落地的自定义Skill示例讲完原理给一个最小可运行的例子。假设我想给OpenCode加一个代码审查Skill。目录结构大致如下~/.config/opencode/skills/code-review/ SKILL.mdSKILL.md的内容是Markdown格式的指令告诉模型触发时机、审查流程和输出模板示意如下--- name: code-review description: 当用户要求审查代码质量、安全或性能问题时使用 --- # 代码审查流程 1. 先读取目标文件或目录。 2. 按可读性、性能、安全性、错误处理四个维度检查。 3. 输出问题列表标注严重程度和建议修改。这个Skill注册后当我在某个会话里提到审查这段代码模型就会在上下文中加载这个Skill的指令按里面定义的步骤去读文件、找问题、按模板输出。整个过程不需要重新编译OpenCode因为Skill是运行时加载的。这也解释了为什么OpenCode把Skills当成扩展体系的核心——它把自定义能力从改代码简化成了写Markdown。5. 从Agent到浏览器Playwright集成怎么做到自己测前端Bug5.1 浏览器工具在源码里的设计OpenCode的Playwright集成是很多人感兴趣的部分因为它让Agent从只能改代码进化为能打开浏览器验证代码。源码里这块的思路和普通工具一样在工具注册表里注册一组浏览器操作比如打开页面、点击元素、读取控制台日志、截图、获取无障碍快照等。模型根据任务目标决定调用哪个浏览器工具工具执行层负责实际驱动浏览器把结果截图路径、console报错、DOM状态摘要转成文本返回给模型循环。值得注意的细节是浏览器工具返回给模型的内容需要精心设计否则上下文会爆炸。源码里通常只返回DOM节点的摘要、关键可访问元素、控制台错误列表而不是把整个页面HTML扔给模型。这个摘要化的设计是所有页面级Agent工具都必须考虑的问题。如果你自己写类似的工具一定要在工具返回层做内容裁剪不然一次页面操作就能把上下文窗口撑爆。5.2 一个可复现的前端Bug检测工作流实际使用中我会让OpenCode做这样一件事打开某个有Bug的页面复现问题收集报错定位到代码文件。一个典型提示词是这样的打开 http://localhost:3000 点击登录按钮不要输入任何内容观察页面是否报错。然后打开浏览器控制台把出现的error信息整理给我并猜测最可能出问题的前端文件。执行过程中Agent会调用浏览器工具完成导航和点击然后读取console内容最后结合仓库代码定位到可疑文件。这个流程在传统开发里可能要手动开DevTools反复点现在Agent可以半自动完成。需要注意它适合用来做冒烟验证和可复现Bug还不能完全替代专业测试用例的编写。从源码角度看这个工作流的本质是Agent在循环里反复使用浏览器工具组每操作一步就观察一次页面状态直到拿到足够信息得出结论。5.3 这套设计可以迁移到什么场景读源码的时候我在想这种Agent浏览器工具的组合完全可以迁移到其他工具上。类似的能力可以用在自动化回归冒烟、页面可访问性检查、视觉回归对比、甚至把多页面操作流程做成一个人工智能驱动的手动测试代理。理解了工具注册和结果摘要化这两点你在任何Agent框架里都能复现这套设计。特别是结果摘要化这个思路是防止上下文爆炸的关键也是很多人自己做浏览器Agent时最容易忽视的地方。6. 源码级排查与二次开发我从踩坑里总结的经验6.1 遇到问题先查日志再反查源码OpenCode报错时很多人第一反应是重装或换key。但更高效的做法是打开日志。源码里日志系统是分模块的会话、工具、模型适配各有各的日志段。遇到invalid api key时先看模型适配段的日志有没有把请求发出、返回状态是什么遇到工具不执行时看工具段有没有参数校验失败。配合日志反查源码基本能解决90%的配置问题。我实际排查过一个case某次切换Provider后一直报鉴权失败配置文件和env都检查了没发现问题。后来翻日志发现配置文件里的Provider id大小写和源码里注册的名字不一致导致走到默认Provider的读取逻辑自然就读不到正确key。这种问题纯靠看README是发现不了的但日志一开、源码一查原因立刻就清楚了。6.2 修改源码重新构建的流程如果你想给OpenCode改点东西比如加一个自定义工具、改TUI配色源码构建流程大致是先确保本机装有合适版本的Bun然后clone仓库、安装依赖、跑开发模式。开发模式里能实时看到改动效果。需要留意的是版本对齐——OpenCode对Bun和Node的版本有要求版本不对会在构建阶段报各种奇怪错误先把运行时版本对齐再动手。构建命令本身不复杂核心就几条bun install装依赖、bun run dev进开发模式、bun run build出生产包。但终端TUI项目有个特点开发模式下改动会热更新但某些底层模块比如原生的文件监听、终端渲染改完必须重启才能生效。你要是改了工具层代码发现没反应先别怀疑改错了重启一下开发进程再试。6.3 值得下手的几个扩展点读完整套源码我个人觉得最值得二次开发的位置有三个新增Provider适配在模型适配层增加一个新的服务商适合有内部模型平台或私有化模型的公司。新增Tool在工具注册表里加一个能力例如执行SQL、操作GitHub PR、调用内部接口。扩展Skill体系把团队规范、代码风格检查做成Skill全团队共享。这几个扩展点的边界都很清晰不会动到核心循环。新手建议从自定义Skill开始零代码成本有一定TypeScript经验的可以从自定义Tool入手成就感最强。新增Tool时重点看工具注册表的数据结构把工具名、参数schema、执行函数三样东西注册进去模型就能在会话里自动发现并调用它。最后再分享一个小体会读OpenCode源码最大的收获不是搞懂了一个具体工具而是看到了一个成熟的Agent运行时该怎么组织模块。工具注册、上下文管理、模型适配、扩展机制这几件事任何想自己做AI编码工具的人都绕不开。如果未来你想在某个垂直场景里做自己的AI助手这份源码会是一个非常值得参考的范本。而且读源码这件事本身有复利效应——你读懂一次后面再遇到任何Agent框架都能一眼看出它的循环在哪、工具怎么注册、上下文怎么管理不会再被花哨的界面和宣传词迷惑。
前阵子把OpenCode拉下来跑通之后我顺手做了个一般人不太会做的事把它的源码从头到尾读了一遍。原因很简单——用的时候它表现很聪明但一旦涉及它到底是怎么做到的文档里很多东西语焉不详。比如Skills为什么能自动触发LSP信息是怎么喂给模型的this model is not available in your country到底是OpenCode的问题还是上游的问题。与其去issue里翻二手答案不如直接把源码打开看一眼。这篇文章就是那轮源码阅读的笔记整理。它是一篇源码解析不是OpenCode的新手教程但我尽量把社区里问得最多的安装、配置、报错问题也带进去因为很多问题的根因恰好就藏在源码里。适合已经在用或者准备深入OpenCode的开发者也适合对AI编码Agent内部机制感兴趣的读者。1. 先别急着看代码OpenCode的定位和源码仓库结构1.1 它不是聊天工具是一个Agent运行时很多人第一次打开OpenCode觉得它是个带界面的ChatGPT。这个印象不准确。OpenCode的核心不是聊天而是在代码仓库里自主执行任务。它背后是SST团队开源的一个AI编码Agent整个运行时的设计目标就是让模型能够观察代码、修改文件、执行命令、调用浏览器并且在多轮工具调用中保持状态。从这个角度理解读它的源码更像在读一个轻量级Agent框架而不是在读一个聊天软件。这也解释了为什么它的模块会分成工具、模型适配、Skill、LSP、浏览器自动化这么几大块。聊天只需要模型API但Agent需要工具系统、上下文管理系统、权限系统和可扩展的接入层。你很难在一款闭源产品里看到这么完整的分层这恰巧是OpenCode很适合做源码解析的原因。1.2 从入口到核心模块源码目录怎么读源码阅读的第一步是把仓库拉到本地。日常使用OpenCode时官方提供了CLI下载方式桌面版和IDE插件比如VSCode、JetBrains也有对应安装包但读源码需要直接clone仓库。拉到后你会发现核心代码是TypeScript写的安装依赖用的是Bun。从功能上分核心代码大致可以切成这么几块TUI界面层负责终端交互、渲染会话、处理输入输出。会话层记录对话历史、管理上下文窗口、处理附加文件。Agent编排层核心决策循环负责调用模型、解析工具调用、执行工具、回填结果。工具层所有工具的注册、参数校验和执行。模型适配层对接Anthropic、OpenAI、OpenRouter、Ollama等服务商。Skill层技能的发现、加载、匹配与执行。LSP层启动语言服务器把语义信息转成模型上下文。浏览器自动化层封装浏览器动作让Agent能真实操作页面。我读源码建议的顺序是先看会话层和Agent编排层理解一次对话怎么流转然后看工具层和模型适配层理解能力从哪来最后看Skill、LSP、浏览器自动化这些增强模块理解它为什么比普通聊天更懂代码。这个顺序是我自己翻了两次源码后总结的能最快建立全局观。不同版本的目录结构会有差异比如2.x比0.x多了桌面端相关代码但大的分层思路基本延续。1.3 为什么选Bun和TypeScript技术选型也值得聊一句。OpenCode选择Bun作为运行时核心原因是性能——终端工具对启动速度和文件IO有很高要求Bun的启动速度和内置工具链让整个CLI的体感响应很快。TypeScript则给这种复杂状态机提供了约束消息、工具参数、Provider返回值都有明确类型读代码时能省很多脑力。如果你打算自己改源码本地Bun版本最好和仓库要求对齐版本不对会在构建阶段报各种奇怪错误这是第一个容易踩的坑。2. Agent主循环一次让AI改代码的请求在内部走了哪几步2.1 从用户输入到工具调用的完整链路这是全文最关键的一段。一次看似普通的把这段代码重构一下背后OpenCode内部的流转是这样的用户输入进入会话层作为user消息追加到消息列表。Agent层把系统提示词、历史消息、当前上下文里的文件内容、所有已注册工具的定义一起打包成一个模型请求。模型返回结果可能是纯文本也可能包含一个或多个工具调用。如果有工具调用Agent不会直接把它交给用户而是先做参数校验和权限检查再调用对应的工具执行函数。工具返回结果被包装成tool消息追加回消息列表。Agent拿着更新后的历史继续请求模型。反复执行3到6步直到模型不再产生新的工具调用最终回复才展示给用户。这就像你让一个实习生干活他不是一口气给你答案而是查资料→给你看→你反馈→再查→再给你看。OpenCode的Agent循环就是把这个实习生写成了代码。模型能不能完成任务很大程度取决于这个循环设计得好不好。2.2 工具调用与结果回流是整个Agent的发动机工具调用这块从源码上看核心可以用下面的类型来理解interface ToolCall { id: string; name: string; arguments: Recordstring, unknown; } interface ToolResult { ok: boolean; data: unknown; error?: string; }消息列表是Agent的记忆每轮工具调用和工具结果都会被完整记录。这样模型在下一次生成时能够看到我调用了read_file读到了xxx内容从而基于真实文件内容做判断。这也是为什么OpenCode改代码时不会凭空乱改——它的上下文里确实有文件内容。源码里的循环逻辑并不复杂本质上就是一个while循环关键在退出条件只有模型不再请求工具时循环才停止。这个设计直接决定了Agent的自主程度。提示如果你在源码里看到某个工具一直没被模型调用先检查工具定义里的description写得是否清楚。模型是靠description决定要不要调用工具的工具名和参数说明写得模棱两可它就不会用。2.3 导入一段代码进行修改在源码上是如何实现的很多网友问opencode怎么导入一段程序代码并进行修改完善。其实在源码里这个动作并不神秘会话层支持把一个或多个文件作为附加上下文注入。注入后文件内容会以明确的分隔格式出现在消息列表里模型的后续回答就有了具体依据。实际操作时你可以在会话里添加文件也可以直接把文件路径拖进输入框让Agent读取后再修改。比起笼统地说帮我优化一下带上文件后模型的输出完全是两个级别。从源码视角看这里最值得关注的是上下文截断策略——文件内容过长时会话层会怎么裁剪这决定了Agent在大仓库里的可用性。3. 模型适配层invalid api key、地区限制、免费模型是同一件事的三面3.1 Provider抽象OpenCode是怎么统一各家模型API的不同模型服务商的API格式、认证方式、流式协议都不一样。OpenCode在源码里做了一层Provider抽象把各家差异挡住。每个Provider都要实现统一的接口发请求、解析流式输出、转成内部Message和ToolCall。对上层Agent来说它根本不关心模型来自Anthropic还是Ollama它只跟统一的抽象打交道。这也带来了一个非常实际的好处你在一个OpenCode会话里可以随时切换模型服务商甚至可以把同一个问题分别发给Claude和本地模型对比答案。切换模型时会话历史是共享的模型适配层负责把相同的历史翻译成不同服务商能理解的格式。源码里各Provider的差异主要集中在请求体构造和流式解析这两块前者各家格式不同后者大多走SSE但要处理的事件字段不一样。3.2 API key到底从哪来环境变量、配置文件和ccswitchinvalid api key是最常见的问题。源码里API key的读取顺序大致是当前目录配置文件、全局配置文件、环境变量。对于大多数Provider最终靠的还是环境变量常见变量名如下模型服务商常见环境变量AnthropicANTHROPIC_API_KEYOpenAIOPENAI_API_KEYOpenRouterOPENROUTER_API_KEYGoogle GeminiGEMINI_API_KEYOllama不需要key本地服务如果你报invalid api key先按这个顺序查环境变量有没有设置、设置的是不是当前选择Provider对应的变量、key有没有多余的空格或换行、key本身是否过期。社区里常见的ccswitch本质上就是把不同服务商的key集中管理在启动opencode前把当前要用的key注入环境变量。它不干预OpenCode内部逻辑所以排查时记得先确认ccswitch注入之后环境变量里真实的值是什么。另外Linux下经常要手动修改JSON配置文件改完注意JSON格式不能有语法错误一个多余的逗号就会让配置加载失败。3.3 this model is not available in your country是谁报的错这个问题在热搜里出现频率很高。可以明确地说这不是OpenCode源码报的错OpenCode不会自己判断你所在的国家它也没有任何地理探测逻辑。这个错误是模型服务商在服务端返回的OpenCode的请求层只是把Provider返回的错误信息原样透传显示在界面上。从源码角度看这个问题发生在模型适配层请求发出后服务商返回了一个错误响应适配层解析错误体把里面的message字段透传出来。所以你不需要去改OpenCode源码更不应该去搜索任何绕过方案。正确合法的做法是换一个在你当前区域可用的模型服务商或者改用OpenRouter这类聚合平台上的可用模型也可以直接用本地模型比如Ollama彻底绕开服务商区域校验的问题。提示当报错信息带有一段请访问我们的支持页之类的文案时基本可以断定是上游服务商的业务限制不是配置错误也不是OpenCode的Bug。3.4 免费模型和本地模型的接入配置说回opencode免费模型。完全免费使用的方案里我实际用过两种一种是OpenRouter上的免费模型另一种是本地Ollama。OpenRouter的好处是它的API格式兼容OpenAI绝大部分Provider适配成本很低。配置上可以这样理解你在opencode.json的provider里指定自定义的base_url和模型id把OpenRouter或者本地Ollama的服务地址填进去。下面是一个本地Ollama的配置思路示意具体字段名以你所用版本为准{ provider: { ollama: { base_url: http://localhost:11434, models: [qwen2.5-coder:7b] } } }本地模型虽然响应速度取决于机器配置但优点是私密性强、没有区域和配额限制适合用来跑一些敏感代码。如果你在意opencode go套餐的响应速度这类问题我的经验是响应速度的根源在模型服务商和网络链路不在OpenCode这个壳。用同一个Provider和同一个模型换任何客户端速度都差不多。与其纠结工具不如从模型本身和网络质量去解决。4. 读懂代码的两种能力Skills与LSP的源码实现4.1 Skills为什么模型会在需要的时候突然学会新技能Skills在OpenCode里是一组可复用的能力包。一个Skill通常包含一段指令文本告诉模型在什么场景下应该做什么、按什么步骤做可以附带脚本作为辅助工具。源码层面的Skill系统大概由三部分组成加载器负责扫描内置和用户目录下的所有Skill匹配器根据当前任务和Skill的描述判断是否值得使用执行器在模型决定使用Skill后把Skill内容注入上下文并运行关联脚本。很多用户问Skill为什么不生效最常见原因是描述写得不够具体。模型是依靠描述来决定何时使用Skill的如果描述含糊比如处理代码它就无法判断该在什么时候用。正确的描述应该明确触发场景例如当用户要求进行前端可访问性审查时使用。源码里匹配器的逻辑其实很简单没有复杂的语义匹配本质上是把描述和当前对话关键词做一次相关性判断所以描述质量直接决定Skill的可用性。4.2 LSP语义信息是怎么喂给模型的LSP是OpenCode另一个重要的上下文来源。说得直白一点模型本身是看不到你工程里的类型定义、函数引用、报错诊断的。LSP的职责就是把语言服务器提供的语义信息整理成模型能读懂的文本片段在合适的时候注入消息上下文。比如Agent要修改一个函数可以先通过LSP拿到该函数的定义位置、所有调用点、当前工作区里的诊断报错这些信息作为工具结果回填给模型让修改更精准。这种设计非常聪明它没有重新发明一套代码分析器而是复用了编辑器生态里最成熟的Language Server。这意味着OpenCode支持的编程语言广度基本等于社区语言服务器的广度。源码里LSP客户端的启动、初始化、请求挂钩、结果格式化都做得比较独立读这一块时不需关注具体语言关注协议交互就行。如果你在自己的工具里也想集成类似能力直接参考LSP层的设计即可。4.3 一个可落地的自定义Skill示例讲完原理给一个最小可运行的例子。假设我想给OpenCode加一个代码审查Skill。目录结构大致如下~/.config/opencode/skills/code-review/ SKILL.mdSKILL.md的内容是Markdown格式的指令告诉模型触发时机、审查流程和输出模板示意如下--- name: code-review description: 当用户要求审查代码质量、安全或性能问题时使用 --- # 代码审查流程 1. 先读取目标文件或目录。 2. 按可读性、性能、安全性、错误处理四个维度检查。 3. 输出问题列表标注严重程度和建议修改。这个Skill注册后当我在某个会话里提到审查这段代码模型就会在上下文中加载这个Skill的指令按里面定义的步骤去读文件、找问题、按模板输出。整个过程不需要重新编译OpenCode因为Skill是运行时加载的。这也解释了为什么OpenCode把Skills当成扩展体系的核心——它把自定义能力从改代码简化成了写Markdown。5. 从Agent到浏览器Playwright集成怎么做到自己测前端Bug5.1 浏览器工具在源码里的设计OpenCode的Playwright集成是很多人感兴趣的部分因为它让Agent从只能改代码进化为能打开浏览器验证代码。源码里这块的思路和普通工具一样在工具注册表里注册一组浏览器操作比如打开页面、点击元素、读取控制台日志、截图、获取无障碍快照等。模型根据任务目标决定调用哪个浏览器工具工具执行层负责实际驱动浏览器把结果截图路径、console报错、DOM状态摘要转成文本返回给模型循环。值得注意的细节是浏览器工具返回给模型的内容需要精心设计否则上下文会爆炸。源码里通常只返回DOM节点的摘要、关键可访问元素、控制台错误列表而不是把整个页面HTML扔给模型。这个摘要化的设计是所有页面级Agent工具都必须考虑的问题。如果你自己写类似的工具一定要在工具返回层做内容裁剪不然一次页面操作就能把上下文窗口撑爆。5.2 一个可复现的前端Bug检测工作流实际使用中我会让OpenCode做这样一件事打开某个有Bug的页面复现问题收集报错定位到代码文件。一个典型提示词是这样的打开 http://localhost:3000 点击登录按钮不要输入任何内容观察页面是否报错。然后打开浏览器控制台把出现的error信息整理给我并猜测最可能出问题的前端文件。执行过程中Agent会调用浏览器工具完成导航和点击然后读取console内容最后结合仓库代码定位到可疑文件。这个流程在传统开发里可能要手动开DevTools反复点现在Agent可以半自动完成。需要注意它适合用来做冒烟验证和可复现Bug还不能完全替代专业测试用例的编写。从源码角度看这个工作流的本质是Agent在循环里反复使用浏览器工具组每操作一步就观察一次页面状态直到拿到足够信息得出结论。5.3 这套设计可以迁移到什么场景读源码的时候我在想这种Agent浏览器工具的组合完全可以迁移到其他工具上。类似的能力可以用在自动化回归冒烟、页面可访问性检查、视觉回归对比、甚至把多页面操作流程做成一个人工智能驱动的手动测试代理。理解了工具注册和结果摘要化这两点你在任何Agent框架里都能复现这套设计。特别是结果摘要化这个思路是防止上下文爆炸的关键也是很多人自己做浏览器Agent时最容易忽视的地方。6. 源码级排查与二次开发我从踩坑里总结的经验6.1 遇到问题先查日志再反查源码OpenCode报错时很多人第一反应是重装或换key。但更高效的做法是打开日志。源码里日志系统是分模块的会话、工具、模型适配各有各的日志段。遇到invalid api key时先看模型适配段的日志有没有把请求发出、返回状态是什么遇到工具不执行时看工具段有没有参数校验失败。配合日志反查源码基本能解决90%的配置问题。我实际排查过一个case某次切换Provider后一直报鉴权失败配置文件和env都检查了没发现问题。后来翻日志发现配置文件里的Provider id大小写和源码里注册的名字不一致导致走到默认Provider的读取逻辑自然就读不到正确key。这种问题纯靠看README是发现不了的但日志一开、源码一查原因立刻就清楚了。6.2 修改源码重新构建的流程如果你想给OpenCode改点东西比如加一个自定义工具、改TUI配色源码构建流程大致是先确保本机装有合适版本的Bun然后clone仓库、安装依赖、跑开发模式。开发模式里能实时看到改动效果。需要留意的是版本对齐——OpenCode对Bun和Node的版本有要求版本不对会在构建阶段报各种奇怪错误先把运行时版本对齐再动手。构建命令本身不复杂核心就几条bun install装依赖、bun run dev进开发模式、bun run build出生产包。但终端TUI项目有个特点开发模式下改动会热更新但某些底层模块比如原生的文件监听、终端渲染改完必须重启才能生效。你要是改了工具层代码发现没反应先别怀疑改错了重启一下开发进程再试。6.3 值得下手的几个扩展点读完整套源码我个人觉得最值得二次开发的位置有三个新增Provider适配在模型适配层增加一个新的服务商适合有内部模型平台或私有化模型的公司。新增Tool在工具注册表里加一个能力例如执行SQL、操作GitHub PR、调用内部接口。扩展Skill体系把团队规范、代码风格检查做成Skill全团队共享。这几个扩展点的边界都很清晰不会动到核心循环。新手建议从自定义Skill开始零代码成本有一定TypeScript经验的可以从自定义Tool入手成就感最强。新增Tool时重点看工具注册表的数据结构把工具名、参数schema、执行函数三样东西注册进去模型就能在会话里自动发现并调用它。最后再分享一个小体会读OpenCode源码最大的收获不是搞懂了一个具体工具而是看到了一个成熟的Agent运行时该怎么组织模块。工具注册、上下文管理、模型适配、扩展机制这几件事任何想自己做AI编码工具的人都绕不开。如果未来你想在某个垂直场景里做自己的AI助手这份源码会是一个非常值得参考的范本。而且读源码这件事本身有复利效应——你读懂一次后面再遇到任何Agent框架都能一眼看出它的循环在哪、工具怎么注册、上下文怎么管理不会再被花哨的界面和宣传词迷惑。
技术解析与实践指南)
)
)
