有段时间没正经写 OpenCode 的配置总结了结果这周被问得最多的问题居然是“OpenCode 配什么 LSP 和 SKILL 最好用”。说实话这问题问得挺到位的因为 OpenCode 这工具现在有点特殊它既不是传统 IDE也不是那种只能聊天的纯 AI 面板而是把 AI agent、语言服务器、技能包全揉在终端里的编程环境。很多人装上 OpenCode 之后发现补全不够准、报错不够清、上下文老跑偏十有八九不是模型选错了而是 LSP 和 Skill 没配明白。这篇文章就围绕 OpenCode 实际使用中的 LSP 选型、Skill 装配、模型搭配和典型报错排查来讲给出一套可以直接照着抄的配置方案。无论你刚安装完 OpenCode 还在观望还是已经用了一段但总感觉差点意思这篇都值得花五分钟读完。顺便开头先说结论现阶段最省心的组合是“按语言挑一个稳定的 LSP 两三个高密度 Skill 一个好模型”三者缺一不可下面展开细说。1. 先把话说清楚LSP 和 Skill 在 OpenCode 里到底管什么很多人一看到 LSP 就条件反射想到 VS Code、Neovim觉得那是给编辑器用的东西和 AI 编程工具有什么关系。这个理解不能说错但放在 OpenCode 的场景里有点低估它了。OpenCode 本质上是一个运行在终端里的 coding agent它能不能精准地读懂代码、定位符号、处理重构靠的不是模型自己瞎猜而是 LSP 提供的结构化信息。1.1 LSP 不是给 IDE 用的吗终端里的 AI 为什么也要它LSP全称 Language Server Protocol就是一套语言服务器和编辑器之间的通信协议。传统用法是 VS Code 跑一个 TypeScript 语言服务器你敲代码的时候它负责告诉你哪里有类型错误、哪个变量能跳转、哪些引用被修改了。OpenCode 这类 agent 工具引入 LSP思路也是一样的只是消费方从“编辑器 UI”换成了“AI 模型”。我举个实际例子你在 OpenCode 里让它改一个复杂函数如果没有 LSP模型只能读取文件里的文本然后基于训练知识猜这个函数的调用关系猜错的概率不低。一旦配好 LSPOpenCode 可以实时查询某个符号的定义位置、当前文件的诊断信息、引用列表模型拿到的就不是一堆死文字而是经过解析的代码语义。这个差别在项目一大、文件一多的时候非常明显复杂度上去了之后模型靠硬读源码猜结构和靠 LSP 喂结构化数据准确率差距能到两三个档次。所以我的建议是OpenCode 装完第一件事就是配置语言服务器而不是急着搞 Skill。LSP 是地基Skill 是上层建筑。地基没打好模型对你的项目永远隔着一层纱。1.2 Skill 与 Agent 有什么不一样Skill 和 Agent 这两个概念在 OpenCode 生态里容易被混着说其实分得很清楚。Agent 是一个能独立执行任务的执行者它有上下文、有工具调用能力、可以在终端里跑命令、读写文件。而 Skill 更像是一份“领域知识包”或者“工作流说明书”它把某个专业场景下的经验、规则、最佳实践打包起来让 Agent 在特定任务里直接调用。举个例子你就懂了比如你给 OpenCode 装了一个“前端重构 Skill”这个 Skill 内部定义了拆分组件的检查清单、命名规范、常见反模式判断条件。当 Agent 接到“重构这个 Page”的任务时它先加载这个 Skill按照里面的流程一步步分析而不是凭模型本能自由发挥。简单说Agent 是执行力的来源Skill 是执行质量的保障。顺着这个逻辑你也可以构思自己的 Skill。观点可能有点个人化但我觉得 Skill 最核心的价值并不是增加多少新功能而是约束 Agent 的行为方式。不带 Skill 的 Agent 像一个聪明但散漫的实习生带了一堆好 Skill 的 Agent 就像一个熟悉团队规范的老手做出来的东西可能更稳、更符合项目预期。1.3 什么时候优先配 LSP什么时候优先配 Skill我的经验是分场景看。如果主要工作是改 bug、重构、跨文件定位符号LSP 优先级最高没有它模型干活等于盲人摸象。如果主要工作集中在特定领域比如 React 组件开发、论文写作辅助、数学建模、语言学习、数据分析那么 Skill 的收益更直接因为它把专家经验直接灌给了模型。一般建议初始配置顺序是先给常用语言配上合适的 LSP再安装两到三个和工作流紧密相关的 Skill最后根据实际使用反馈持续调整。这套流程基本覆盖了大多数人的核心需求下面的章节我会按这个顺序逐步展开。2. LSP 配置实操不同语言怎么选、怎么配LSP 选配这件事最怕的就是一上来装一堆服务器结果项目里根本用不到反而拖慢启动速度、增加 CPU 占用。OpenCode 的 LSP 配置是按项目走的你完全可以每个项目只开当前语言需要的那个服务器。2.1 LSP 的选型逻辑先说我选 LSP 的几条硬标准第一对应语言官方维护或社区公认活跃的尽量不选三五年没更新的第二能吃下完整的项目上下文而不是只对单个文件生效第三启动速度快、内存占用别太夸张。拿几个典型场景举例写 TypeScript 首选 TypeScript 官方出的 typescript-language-server它和 tsserver 同源对类型推导、跳转、引用的支持最准Python 项目我更推荐基于 Pyright 的 pyright-language-server而不是 pylsp因为前者对类型标注的理解明显更强配合 Agent 做重构时给出的诊断信息更可靠Go 基本没有悬念gopls 就是官方标准Rust 用 rust-analyzer这一点也不需要讨论。这里有个容易被忽略的细节LSP 的“诊断能力”对 AI Agent 的帮助比“补全能力”重要得多。编辑器里的 LSP 主要靠补全和跳转提升写码速度但 Agent 需要的是错误定位、类型不匹配、引用断链这类诊断信息。配置的时候优先看语言服务器的诊断质量别被补全手感骗了。2.2 项目级配置怎么写OpenCode 的 LSP 配置主要写在项目根目录的配置文件里。以 opencode.json 为例一个最简单的 TypeScript Python 双语言项目可以像下面这样配{ lsp: { typescript: { server: typescript-language-server, args: [--stdio], extensions: [.ts, .tsx, .js, .jsx], project: . }, python: { server: pyright-language-server, args: [--stdio], extensions: [.py], project: . } } }配置项看着不多实际上有几个点值得细说。extensions决定哪些文件后缀会触发出对该 LSP 的请求建议精准一些比如 TypeScript 配.ts、.tsx、.js、.jsx没必要混入.vue或.svelte因为那些文件通常也有自己的语言服务器project字段指定项目根目录这决定了 LSP 在哪个范围里索引代码如果项目比较大建议指向子目录或者用 monorepo 包级别定位避免把所有无关代码都索引一遍否则首次启动会慢到你怀疑人生。2.3 按语言推荐的 LSP 清单为了让你直接抄作业我把常见语言的推荐配置整理成一个表这些组合我现在还在用实测稳定度都很高。语言推荐 LSP启动方式备注TypeScript / JavaScripttypescript-language-server--stdio官方 tsserver类型诊断最准Pythonpyright-language-server--stdio类型标注支持好重构友好Gogopls--stdio官方工具链自带稳定Rustrust-analyzer--stdio复杂项目最佳选择Javaeclipse-jdtls--stdio启动慢但分析完整Lualua-language-server--stdio单独 Lua 项目用启动快C/Cclangd--stdio需要 compile_commands.json表格里特别提醒一下 Java 的 eclipe-jdtls之前有几次我图省事用了别的轻量方案结果大型项目里类路径全部解析失败诊断信息基本没法用最后换回 jdtls 才正常。Java 生态的 LSP 没有捷径省那点启动时间不值得。2.4 配置时的禁忌与细节配置 LSP 有几个坑我逐个踩过现在基本形成了条件反射。第一个坑是同一语言装了多个 LSP。有的 LSP 之间有地址冲突比如同时起 tsserver 和通过其它方式代理的 TS 补全Agent 收到两份诊断信息之后上下文会被干扰。如果你发现模型改代码的时候总在纠结“另一个工具提醒的类型错误”多半是这个原因。解决方案很简单每种语言只保留一个 LSP。第二个坑是忽略了 LSP 的启动时机。有些配置写完OpenCode 不会立即拉起语言服务器需要重新打开项目或者执行一次重载命令。判断 LSP 到底起没起来最简单的方法是查看启动日志里有没有language server started之类字样再就是观察 Agent 对自己代码的描述是否突然变得具体了——比如能直接说出“第 37 行的接口定义”而不是含含糊糊说“那个地方”。第三个坑是 monorepo 场景下没搞清楚 LSP 的 project 根。monorepo 里如果直接指到仓库根LSP 会把所有包全部索引一遍如果只指到当前包又可能拿不到跨包引用的完整信息。我的做法是先用仓库根配测试之后如果发现索引太慢再缩小范围加一份针对核心包的配置。灵活调整比一步到位靠谱。3. Skill 推荐与实战按需求挑技能包LSP 解决的问题是“让模型看得准”Skill 解决的问题是“让模型做得对”。两者定位完全不同但配合起来效果叠加。这一节我把 Skill 的安装、编写和推荐一次性讲完。3.1 Skill 的本质与安装方式在 OpenCode 里Skill 本质上是一个包含说明文档和可选脚本的目录通过一个描述文件告诉 Agent“这个技能是什么、什么时候用、怎么用”。和传统插件不同的地方在于Skill 的内容高度可读、可编辑你完全可以用纯文本把它写出来并在使用的过程中不断迭代。安装 Skill 通常有两种途径一是使用现成的 Skill 市场或仓库把对应目录克隆到 OpenCode 的 skill 路径下二是自己建一个目录手动写。我个人强烈建议学会第二种因为现成 Skill 往往针对通用场景属于基本盘真正能提升效率的往往是你们自己项目需求的定制 Skill。举个例子我给自己写了一个“Code Review Skill”要求 Agent 在收到 review 任务时先检查改动文件是否涉及核心模块、是否存在明显的错误处理缺失、是否遵循了项目的命名规范最后按严重程度输出问题清单。这个 Skill 描述文件不长但它在每次代码审查任务里强制模型走了一遍检查流程效果比我每次在 prompt 里重复叮嘱要好得多。3.2 核心 Skill 目录和描述怎么写一个最小可用的 Skill 目录结构大概长这样my-skill/ SKILL.md scripts/ run.shSKILL.md 是灵魂文件它负责描述技能的元信息和调用逻辑。里面可以包含 YAML 风格的前置信息也可以包含大段的 Markdown 说明。我习惯这么写--- name: code-review description: 用于代码审查场景按项目规范逐项检查改动质量 --- # Code Review Skill 当收到 review 或 代码审查 相关任务时按以下步骤执行 1. 读取 git diff列出所有变更文件 2. 逐个检查变更是否涉及核心模块 3. 检查错误处理、边界条件是否合理 4. 检查命名和代码风格是否符合项目规范 5. 输出问题清单按严重程度排序这里的description字段特别重要因为 Agent 判断什么时候加载这个 Skill主要就是靠它。描述写得越具体匹配准确率越高。比如“用于代码审查场景”就比“审查代码”好用因为它把触发场景点得更明确。如果你想让 Skill 在真实 Agent 环境里更强大还可以加上 Action 定义给 Skill 绑定可执行的工具或脚本。这样 Skill 不只是静态规则还能驱动 Agent 调用命令去拉取 git 状态、运行自动化检查算是一个进阶玩法。3.3 值得装的几类 SkillSkill 不能乱装装少了没用装多了模型每次都要在大量候选里做筛选反而拖慢响应。按我的实操经验普通用户保留三到五个高质量 Skill 是最舒服的状态。下面这些方向是我实际用下来认为性价比最高的前端最佳实践类适合 React、Vue 项目内置组件拆分规范和常见反模式清单论文与研究辅助类对于做学术写作的特别友好能强制 Agent 按“摘要-引言-方法-实验-结论”的结构去组织内容数学建模类让 Agent 在建模任务里优先考虑模型选择、假设条件、参数敏感性适合竞赛和课题语言学习类用于口语练习、语法纠错、造句训练要求 Agent 扮演陪练而不是直接给答案代码规范类类似我的 code-review Skill但侧重风格约束和提交信息规范。有一个搜索热度很高的词叫“仓颉 skill”说的是为仓颉这门较新的编程语言专门做的技能包。如果你在学新语言或者公司内部有类似的自研语言完全可以参照这个思路把语言语法要点、常见坑位、惯用法写进 Skill效果非常直接。Skill 这个东西最大的特点就是“可定制”别把它当成一成不变的成品插件。4. 模型与运行环境的搭配好的 LSP 和 Skill 也需要靠谱的“大脑”配好了 LSP装好了 Skill如果模型本身太弱前面这些努力还是白搭。现实中很多人问“为什么我配了这些感觉没啥用”排查到最后往往发现是模型选错了或者环境出问题了。这一节单独讲模型与运行环境尤其是几个高频问题。4.1 常见报错opencode free tier can only be used from within opencode先说一个几乎所有人都会碰到的报错命令行里会冒出一句类似error from provider (console): opencodes free tier can only be used from within opencode。这个报错的意思是你试图在 OpenCode 终端环境之外调用它的免费额度接口比如在脚本里直接 curl 了某个 API或者在另一个应用里把它当普通接口来用而 OpenCode 的免费额度限定只能在它自己的终端会话内使用。我刚遇到这个报错时也愣了一下第一反应是网络问题后面仔细读了提示才知道是上下文问题。解决方式一般不复杂确认你在 OpenCode 的交互终端里运行而不是外部进程重新登录或重启会话基本就好如果你是集成到别的地方调它的接口那就该换个思路了要么用官方推荐的认证方式要么直接配置自己的模型 API Key别盯着免费额度薅。这个报错其实侧面说明了 OpenCode 产品的定位它想把完整的 agent 体验闭环在自己终端里而不是变成一个人人可调用的开放 API。出现这个报错不用慌先检查使用场景是否合规再考虑换个接入方式。4.2 模型选择与 OpenCode GoOpenCode 本身并不绑定某一家模型可以在配置里指定多种模型供应商。根据我的测试体验代码生成、重构类任务Claude 系列和 GPT 系列的表现都足够好如果你更看重响应速度、上下文长度、成本控制也可以接一些更轻量的模型跑简单任务再在复杂任务切换到大模型。最近被问得比较多的还有 OpenCode Go很多人好奇它到底是什么。OpenCode Go 可以理解成官方提供的托管运行环境和模型网关你本地起一个会话之后可以把一些长任务丢到 Go 模式里跑这样不用一直开着终端盯着。如果你是跨设备使用比如白天在办公室电脑上开了一个会话晚上回家想接着干OpenCode Go 的云端会话能力就很有用。它的核心价值是让任务不依赖单台机器的持续在线。这里想多说一句在 OpenCode 里模型和 Skill 的关系有点像“大脑”和“肌肉记忆”。模型负责理解和推理Skill 负责提供稳定路径。用再好的模型如果没有 Skill 约束行为效果可能很飘反过来Skill 写得再好模型太弱也执行不出质量。所以我的建议是模型选主流旗舰级Skill 选真正贴合工作的那两三套别贪多。4.3 查看 Token 消耗与成本控制用 OpenCode 这种 agent 工具最怕的就是不知道钱花在哪了。模型每次读写文件、调用工具、生成回复都会消耗 token一个复杂任务可能轻松烧掉几万 token。在 OpenCode 里查看 token 消耗一般有两个入口一是会话结束后的统计区域会列出本次会话的输入输出 token 和各模型用量二是在配置里打开 debug 或 verbose 日志模式让每次请求的 token 数直接打到日志里。建议每次跑完长任务都扫一眼消耗时间久了你会对自己项目的 token 成本有一个大致的感觉。成本控制方面有几个实操技巧给长文档类的 Skill 编辑描述时精简一些不要每次任务都加载一堆用不上的内容尽量让 Agent 少做无意义的全量文件扫描能用 git diff 就看 diff别让它通读整个仓库简单任务明确指定轻量模型重活才切旗舰模型。这些细节看上去很小乘以每天几十次调用之后节省的成本非常可观。5. 常见问题与排查技巧实录最后把这段时间里被反复问到的问题整理一下基本都是安装、配置、运行层面的。整体做成一个可快速查阅的清单比看长篇文档方便。我也顺带把排查思路写进去了。5.1 安装与扩展问题问得最多的是 OpenCode 怎么安装。这个要根据系统来选方式macOS 或 Linux 用安装脚本就能拉起来Windows 则可以用包管理器安装或者跑官方提供的安装命令。安装完成后一般会自动把opencode加到 PATH 里如果出现找不到命令的情况大概率是 PATH 没生效重开一个终端窗口基本能解决。还有朋友问“cursor 的扩展搜不到 opencode”这大概率是把 OpenCode 当成了某个编辑器插件。OpenCode 本身是一个独立的终端工具不是 VS Code 或 Cursor 的插件体系。虽然有人写了一些第三方集成让两者联动但那属于额外玩法不是标配。如果你就是想和编辑器配合建议先跑通终端版的 OpenCode再考虑扩展联动。5.2 运行与连接问题“opencode 归档后去哪了”这个问题我一开始也没看懂后来确认了这里说的归档不是文件归档而是会话归档。OpenCode 的老会话会被归档起来你可以通过历史列表把它们重新调出来继续用。如果找不到归档入口大概率是版本差异问题更新到 v2 之后界面和命令都有所调整归档功能的位置也变过。另一个高频问题是 token 消耗怎么看在第 4.3 节已经讲过。还有一个不算问题但很多人会犯迷糊的OpenCode 装了桌面版之后还要不要命令行版。其实桌面版和命令行版可以共存桌面版给不习惯终端的用户一个图形入口命令行版适合脚本化和远程场景。两者共享会话数据实际使用中建议选一个当主力另一个备用。5.3 问得最多的问题速查问题现象可能原因解决方案补全/跳转没反应LSP 没正确加载检查语言服务器是否安装、配置 extensions 是否正确Agent 总读不准代码结构LSP 缺失或配置错误按 2.2 节项目级配置重新设置free tier 报错在 OpenCode 外调用免费额度在 OpenCode 终端内使用或配置自己的 API KeySkill 不生效描述不匹配或路径不对检查 SKILL.md 的 description 字段确认目录位置会话档案找不到版本差异或入口变更升级到新版后用历史列表查找或执行对应命令模型回复质量飘模型过弱或 Skill 过载切换旗舰模型精简 Skill 到核心三到五个表里这些场景都是真实高频问题你可以当成排查手册用。遇到新问题的时候我的通用排查顺序是先看日志、再看配置、最后怀疑模型。日志里通常记录了 Agent 每一步的思考过程和工具调用情况能快速还原现场比反复试配置高效得多。最后再分享一个小技巧配置完 LSP 和 Skill 之后别急着跑复杂任务先让 OpenCode 自己总结一下当前项目的结构和已经加载的能力。如果它能准确说出项目有哪些目录、哪些核心依赖、装了几个 Skill 以及每个 Skill 的用途说明环境基本没问题了。这个“自检式”的验证方法能帮你节省大量排查时间也是我最近用得最顺手的一个习惯。