从第一次在终端里敲下opencode到现在我大概用了三周时间已经把日常不少编码工作搬到这个命令行 AI 助手里了。说实话一开始我只是被它的 CLI 交互方式吸引毕竟用惯了 Cursor 这类图形界面想看看纯终端 大模型能玩出什么花样。结果用下来发现它比我预期的要成熟得多既能对话也能直接读写项目文件还支持 Skills 扩展机制。这篇文章我不打算写成一板一眼的说明书就按我自己的折腾路径来把安装、配置、模型、VSCode 集成、改代码、Skills、常见报错这些全部串一遍希望能给你省点时间。1. 先从整体上认识 OpenCode1.1 它跟 Cursor、Copilot 的本质区别先回答一个最常被问的问题OpenCode 到底是什么我通常会这么解释它是一个跑在终端里的开源 AI 编程助手交互方式是对话但它不像普通聊天机器人那样只能在对话框里给你贴代码它可以直接读取你项目里的文件、修改内容、执行命令甚至帮你跑测试。核心是 Agent 模式也就是说它不只是回答而是干活。和 Cursor、GitHub Copilot 相比OpenCode 最大的不同在于两点。第一它没有绑定某个特定厂商的模型。你可以自己选择接 Anthropic 的 Claude、OpenAI 的 GPT、Google 的 Gemini也可以接本地跑的模型或者用 OpenCode 官方提供的免费体验模型。这个自由度在 Cursor 里也有但 OpenCode 天然是 CLI 气质配置文件写在本地切换模型非常直接。第二它的资源占用和启动速度是真的快。终端应用嘛没有一整套 IDE 的负担打开一个项目目录就能进入会话。我用一台配置一般的老笔记本试过启动 OpenCode 基本就是瞬开输入命令、看到提示符、开始对话整个过程比打开一个重量级 IDE 快得多。1.2 核心能力到底有哪些我整理了一下日常用得最多的几个能力你可以对照着看多模型对话与切换同一个会话里可以指定不同的模型也可以在配置里设置默认模型。Agent 自动改代码这是我最依赖的功能。告诉它需求它会自己看文件、改文件然后运行相关命令验证。Skills 扩展机制类似于给 AI 预置技能比如代码审查、写单元测试、生成提交信息每个 Skill 是一套带指令的配置。项目上下文感知启动时读取项目结构结合.gitignore等规则只把有效文件纳入视野。批量文件操作一次对话里可以涉及多个文件适合做跨文件的重构和调整。终端命令执行它可以在你的终端里执行测试、构建等命令然后根据输出来决定下一步动作。换句话说OpenCode 几乎覆盖了 Cursor 这类工具的日常高频操作只不过交互层从图形界面换成了命令行。适应之后效率反而更高因为所有操作都能用键盘完成手不用在鼠标和键盘之间来回挪。1.3 什么样的人适合用它我自己用过一段时间后觉得下面几类人最容易从 OpenCode 里获得价值习惯终端工作流的人日常用 Vim、Neovim、tmux或者在服务器上开发调试OpenCode 是天然契合的。想摆脱 IDE 依赖的人有时候只是临时改点东西没必要为一个需求启动整个 IDE。对模型有掌控欲的人在不同项目里想用不同模型或者想接自己私有模型OpenCode 的配置方式更透明。做批量重构和代码审查的人Agent 模式加上自定义 Skills处理重复性工作很顺手。当然如果你是完全没接触过命令行的纯新手我建议你先从 VSCode 插件入手后面我再细讲这个用法。2. 安装与环境准备2.1 三种安装方式总有一种适合你OpenCode 的安装方式主要分三种官方脚本安装、Go 工具链安装、包管理器安装。我全部试过说一说实际体验。官方脚本安装是最省事的终端里执行安装命令然后它会自动把可执行文件放到~/.opencode/bin之类的目录里。装完之后需要把目录加进 PATH一般安装完了它也会提示你怎么加。如果你本机已经有 Go 工具链直接用go install安装也很方便下载的是当前开源仓库的代码编译产物适合想跟进最新功能的朋友。不过好处和坏处都很明显Go 版本有要求太老的版本可能导致编译失败我踩过一次升级 Go 之后就好了。包管理器方面macOS 用户可以用 HomebrewLinux 用户看发行版选择。这种方法的好处是卸载和升级都方便但包的更新速度可能不如官方渠道快偶尔会落后一两个小版本。如果上述方式都不方便OpenCode 还提供桌面版。桌面版本质上还是基于 CLI 核心只是加了一个图形外壳提供会话列表、设置面板对不习惯纯终端操作的人友好了很多。提示装完先不要急着用确认一下版本号opencode --version能正常输出版本就说明安装成功。如果提示找不到命令八成是 PATH 没配好。2.2 配置 API Key分几步走OpenCode 本身不生产模型它只是模型服务的客户端。所以你要用自己的模型服务就得先配置 API Key。配置方式我记得有三种环境变量、配置文件、交互式登录。环境变量最直接比如用 OpenAI 兼容的服务就设置OPENAI_API_KEY这类变量但如果你同时接好几个不同的模型服务全用环境变量会乱。我更推荐用opencode auth login交互式登录它会显示一个提供商列表你选择之后按提示粘贴 API Key信息会被写进本地的认证文件里后续使用不用再重复输入。配置文件的方式适合想把所有团队成员的模型配置统一起来的情况。OpenCode 使用一个opencode.json或opencode.jsonc作为项目级配置可以指定每个模型的 provider、base URL 和密钥引用。把密钥放在配置文件里时要小心别手滑提交到 Git 仓库我一般会在.gitignore里把包含密钥的配置文件忽略掉。2.3 添加和管理模型配置完 API Key 只是第一步你还得告诉 OpenCode 你到底有哪几个模型可以用。查看当前可用模型列表是opencode models这个命令会列出所有已经能访问的模型名称、所属提供商以及是否被标记为默认模型。如果想添加一个新模型路径通常是在配置文件的model或models区域里声明指定provider、name、baseUrl等字段然后重启会话让配置生效。这里有个常见的坑不同模型服务商对模型名称的命名不一样同一个模型在不同服务商那里可能有完全不同的字符串填错了会直接报错。我的习惯是先去服务商文档确认模型 ID再填到配置里不要凭印象写。OpenCode 还支持提供商的概念你可以把一组 API Key 和 base URL 打包成一个 provider。这样多个模型可以共用同一个 provider 的密钥配置管理起来清晰很多。3. 模型选择、免费额度与订阅方案3.1 免费模型到底够不够用OpenCode 官方提供了一些免费体验模型不需要你自己申请 API Key 就能直接试用。对新手来说这是最友好的入口装完软件连上官方服务直接开聊。但免费模型通常有速率限制、上下文长度限制而且偏向小参数模型应付简单的代码问答、脚本生成没问题真让它理解一个大型项目能力可能不够。我自己的建议是先用免费模型把 OpenCode 的交互流程跑通确认它能满足你的工作习惯然后再去申请更强大的模型服务。等于是把免费模型当成试用装别指望它解决所有问题。如果你手头已经有其他 AI 平台的 API Key不管是哪家只要它提供 OpenAI 兼容的接口就有很大概率能接到 OpenCode 里。在配置 provider 时选择openai兼容模式填上对应的 base URL 即可。3.2 付费订阅和套餐怎么选关于订阅计划我看到很多人直接把 OpenCode 和某些云服务商的套餐混在一起问。这里我提醒一句OpenCode 是开源软件本身的代码是免费使用的你花钱买的是模型调用的额度钱是付给模型服务商的不是付给 OpenCode 的。那怎么选套餐我一般看这么几个维度使用频率、模型档位、上下文需求。轻度用户每周用几次主要是代码问答、写点小脚本免费模型或者按量付费的轻量套餐就够。中度用户每天都会用需要它改代码、跑测试建议选一个能覆盖主流强模型的套餐注意看请求次数限制。重度用户长时间开着 Agent 模式动不动就跨文件重构这类使用会消耗大量 token建议选不限次或高配额的套餐同时自己也要控制对话长度。注意具体套餐内容、价格、包含哪些模型变化很快一定要以官方最新页面为准别看我这一篇文章就下单。我只能说大方向优先选提供按量付费的套餐这样用多用少心里有数不会浪费。3.3 遇到model not available in your country怎么办这个报错我见过不少次因为它属于模型服务商对调用来源区域做的限制。当你选择的模型在某个地区不可用OpenCode 会直接返回类似This model is not available in your country的错误。处理思路有几种先确认你配置的模型 ID 是否拼写正确有时候明明是模型 ID 写错服务商返回的却是地区不可用误导性很强。换一个服务商提供的备用模型很多服务商同一系列还分成不同版本某些版本限制少一些。联系服务商的官方支持确认你的账号是否有权限调用该模型以及该区域当前是否在开放列表里。这里必须强调一下不要通过任何绕过限制的方式去访问原本不可用的服务这不是技术问题是合规问题。最稳妥的做法就是换模型、换服务商或者等官方开放。4. 在 VSCode 里把 OpenCode 用起来4.1 安装插件与基本设置虽然 OpenCode 是终端工具但它在 VSCode 里也有插件我是在需要同时看代码、聊 AI 的场景下开始用插件版的。安装很简单在 VSCode 扩展商店搜索 OpenCode装好之后左侧会出现一个 OpenCode 图标点开就是一个对话面板。插件版的底层调用的是同一个 CLI 核心所以你之前在终端里配置好的 API Key、模型、Skills它都能直接复用。首次使用时它会检测本机是否已安装 OpenCode如果没有会引导你安装。这个设计很贴心不会出现插件装了但跑不起来的情况。设置方面插件版提供几个常用选项默认模型、主题跟终端保持统一、是否自动读取当前打开文件作为上下文。我建议开启自动读取当前文件这个选项这样你在面板里问问题它默认就能看到光标所在文件的内容省得每次手动指定。4.2 常用操作与我的习惯做法插件版的核心操作就一个选中代码按快捷键把内容送进对话。如果你想把整个文件作为上下文可以直接在面板里输入/file指令然后把路径给它。通常我的工作流是这样的先点开侧边栏的 OpenCode 面板把当前文件送给它然后提出一个具体的修改需求比如把这个函数改成异步版本保持接口兼容。它会在面板里给出修改建议我觉得没问题就手动应用到文件如果改动很大我会提示它直接修改文件然后我再在编辑器里审查 diff。有一点必须提醒无论是插件版还是终端版OpenCode 自动改代码之后你都应该自己 Review 一遍改动尤其是涉及数据库操作、文件删除、权限变更这类高风险场景。它再强也只是辅助工具最终责任在你。5. 把已有代码交给 OpenCode 修改完善5.1 如何把一段程序代码导入进去很多人刚接触 OpenCode 时会问我有一段代码怎么让它帮我改其实方式很多你选一种顺手的就行。最直接的方式在终端里进入项目目录运行opencode然后在对话里把代码粘进去。但我不推荐在代码很长时这么做因为会占用大量上下文 token而且容易丢失格式。更好的方式是让 OpenCode 直接读取文件。启动时它会自动加载当前目录的项目结构你只需要在对话里说打开 src/utils.ts或者看一下 components/Button.tsx它就能自己读取文件内容。如果文件路径太长你也可以用/file指令指定。如果你只想针对一段代码做局部修改可以把那段代码高亮复制到对话里再加一句基于这段代码帮我做 X。这样它的注意力会集中在你贴出来的部分响应更精准。实操心得我习惯在对话里先给它一个明确的文件范围。比如只看 src/pages 和 src/api 这两个目录下的代码不要动其他文件。这个要求能大幅减少它读无关文件的概率也降低改乱其它代码的风险。5.2 一个完整的修改完善流程我拿一个实际的例子来走一遍流程。假设我有一个 Go 项目里面有个 HTTP 接口处理函数逻辑有点乱我想让 OpenCode 帮我重构顺带补一个单元测试。第一步启动 OpenCode它会自动读取项目结构。第二步输入指令先看 handler.go 里的 CreateUser 函数我需要它拆成两个函数一个做参数校验一个做实际的创建逻辑。保持对外接口和返回格式不变。第三步它读取文件后会给出一个修改方案。有时候它直接改文件有时候只是给建议。我会让它直接改改完用git diff看变更。第四步继续提要求给拆分后的两个函数各写一个单元测试覆盖校验失败和创建成功两个分支。它会在项目里新增测试文件然后我执行go test ./...看结果。如果测试挂了把报错信息回贴给它它会接着调。整个过程下来最耗时的反而不是 AI 生成代码而是我 Review 它的改动。但在传统开发模式下从拆分函数到写测试可能得花大半天用 OpenCode 辅助我把时间压缩到了半小时左右。5.3 上下文管理的几个技巧Agent 模式一旦用起来最怕的是它忘记之前的对话内容。OpenCode 的上下文窗口是有限的对话越长早期信息越容易被压缩或忽略。我常用的技巧有三个阶段性开新会话。每完成一个小任务就把对话清掉新开会话接着下一个任务避免上下文越滚越臃肿。用文件路径显式引用文件。在对话里指定某个文件作为当前焦点比让它从历史对话里猜更靠谱。关键需求写在最前面。每次对话开头用一句话概括当前目标和约束条件比如目标是让所有测试通过不要修改公共接口这样即便中途聊偏了它也能回到主线。6. Skills 扩展与高级玩法6.1 Skills 到底是什么用了一段时间 OpenCode你会发现它默认的对话能力是有边界的。比如你想让它按团队规范生成提交信息或者按固定格式做代码审查每次都临时去描述规则既费 token 又容易出偏差。Skills 机制就是用来解决这个问题的。简单说Skills 是预先定义好的指令包。你可以把一段常用的提示词、约束条件、甚至一些示例打包成一个 Skill。需要时在对话里输入/skill名它就会把对应的指令注入这次会话让 AI 按照你预设的规则行事。比如我给自己配了一个叫code-review的 Skill内容大致是请审查当前文件的安全性和性能问题重点检查 SQL 注入、并发安全、内存泄漏输出格式为问题摘要、风险等级、修复建议。每次做代码审查我只要输入/code-review再指定文件它就会按这个模板输出。6.2 如何配置和使用自己的 SkillSkills 的配置方式在不同版本里略有差异但基本思路一致。通常你要在配置目录下新建一个skills文件夹里面每个子文件夹对应一个 SkillSkill 的指令写在一个 Markdown 文件里。以我配的commit-messageSkill 为例流程是在配置文件所在目录下创建skills/commit-message文件夹。在里面创建一个 Markdown 文件简要描述这个 Skill 的用途。文件正文里写清楚生成提交信息时的规范格式、必填项、禁止事项、示例。重启 OpenCode在对话里输入/commit-message测试它会读取当前 Git 变更并生成符合规范的提交信息草稿。这个机制用熟之后你完全可以把团队的编码规范、接口设计约定、测试要求全部沉淀成 Skills。新成员加入时只要导入同一份配置AI 的行为方式就会保持一致。7. 常见问题与排查实录7.1 invalid api key 到底是什么问题这个报错几乎是所有 AI 工具使用者都会遇到的所以我单独拎出来说。它的含义很直接你用 OpenCode 去调用模型服务服务商校验 API Key 不通过于是拒绝了请求。导致这个报错的原因我归纳成四类Key 本身写错了粘贴时多了空格、漏了后半截、或者把别的服务的 Key 填过来了。Key 已失效服务商后台可能因为欠费、过期、安全策略等原因撤销了 Key。环境变量和配置文件冲突某个地方设置了旧的 Key覆盖了新的。提供商选择错了比如 Key 是 A 平台的但你在 OpenCode 里选的 provider 是 B 平台Base URL 就串了。排查顺序我建议先opencode auth list看看当前用了哪个认证再检查配置文件里的 provider 设置最后去服务商后台确认 Key 状态。如果都查不出问题把日志等级调高再跑一次看具体报错里带不带请求的 URL 信息。7.2 模型对话乱码或中文输出乱掉遇到中文乱码的情况首先怀疑终端编码。opencode在有些老终端环境下UTF-8 支持不完整输出中文就会出现乱码。解决办法是把终端切到支持 UTF-8 的版本或者手动设置LANGzh_CN.UTF-8这类环境变量。如果不是终端问题那就可能是模型本身对中文的响应不稳定。换一个中文能力更强的模型或者把你要它处理的内容明确用中文重述一遍让它别切换语言。7.3 怎么设置成中文界面OpenCode 的界面语言一般跟随系统语言设置如果你的系统是英文界面默认就是英文。想改成中文可以在配置文件里设置语言项或者启动时指定语言参数。具体配置项每个版本略有不同最稳妥的方法是运行opencode /help或查看当前版本文档里关于语言设置的说明。另外要注意界面语言和模型回复语言是两回事。界面是中文、模型用英文回复很正常你可以在对话里注明用中文回答它一般都会照做。7.4 其他高频问题速查我把平时群里见到的其他高频问题整理成一张速查表现象常见原因处理思路启动后直接闪退版本冲突或缺少依赖升级到最新版本或查看启动日志对话一直转圈不响应网络问题或模型服务过载检查网络换一个模型试试读取不到项目文件目录权限不足检查目录权限确认不是加密文件夹自动改代码时改了无关文件上下文范围太大在对话里明确限制文件范围命令执行失败子命令不存在确认终端里的工具链已经安装完整插件版连不上 CLI 核心版本不匹配把 CLI 和插件都升级到最新这篇文章从头到尾把 OpenCode 的安装、配置、模型选择、VSCode 集成、代码修改、Skills 和常见报错都过了一遍。最后我再补一个自己的心得别指望 AI 一步到位好的用法是让它先给出方案框架你再逐步修正方向。我见过太多人一上来就让 AI 直接改大文件改完满屏报错最后反而觉得工具不好用。实际上OpenCode 这类 Agent 工具最适合的用法是把它当成一个可以随时讨论方案、快速出草稿、帮忙跑命令的结对程序员而不是一个能完全交付项目的黑箱。你给它的指令越清晰它的产出就越可控。