从第一次在终端里敲下opencode到现在，我大概用了三周时间，已经把日常不少编码工作搬到这个命令行 AI 助手里了。说实话，一开始我只是被它的 CLI 交互方式吸引，毕竟用惯了 Cursor 这类图形界面，想看看"纯终端 + 大模型"能玩出什么花样。结果用下来发现，它比我预期的要成熟得多：既能对话，也能直接读写项目文件，还支持 Skills 扩展机制。这篇文章我不打算写成一板一眼的说明书，就按我自己的折腾路径来，把安装、配置、模型、VSCode 集成、改代码、Skills、常见报错这些全部串一遍，希望能给你省点时间。
1. 先从整体上认识 OpenCode
1.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 用户可以用 Homebrew，Linux 用户看发行版选择。这种方法的好处是卸载和升级都方便，但包的更新速度可能不如官方渠道快，偶尔会落后一两个小版本。
如果上述方式都不方便，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 如何配置和使用自己的 Skill
Skills 的配置方式在不同版本里略有差异，但基本思路一致。通常你要在配置目录下新建一个skills文件夹，里面每个子文件夹对应一个 Skill，Skill 的指令写在一个 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 的版本，或者手动设置LANG=zh_CN.UTF-8这类环境变量。
如果不是终端问题，那就可能是模型本身对中文的响应不稳定。换一个中文能力更强的模型，或者把你要它处理的内容明确用中文重述一遍，让它别切换语言。
7.3 怎么设置成中文界面
OpenCode 的界面语言一般跟随系统语言设置，如果你的系统是英文，界面默认就是英文。想改成中文，可以在配置文件里设置语言项，或者启动时指定语言参数。具体配置项每个版本略有不同，最稳妥的方法是运行opencode /help或查看当前版本文档里关于语言设置的说明。
另外要注意：界面语言和模型回复语言是两回事。界面是中文、模型用英文回复很正常，你可以在对话里注明"用中文回答"，它一般都会照做。
7.4 其他高频问题速查
我把平时群里见到的其他高频问题整理成一张速查表：
| 现象 | 常见原因 | 处理思路 |
|---|---|---|
| 启动后直接闪退 | 版本冲突或缺少依赖 | 升级到最新版本，或查看启动日志 |
| 对话一直转圈不响应 | 网络问题或模型服务过载 | 检查网络，换一个模型试试 |
| 读取不到项目文件 | 目录权限不足 | 检查目录权限，确认不是加密文件夹 |
| 自动改代码时改了无关文件 | 上下文范围太大 | 在对话里明确限制文件范围 |
| 命令执行失败 | 子命令不存在 | 确认终端里的工具链已经安装完整 |
| 插件版连不上 CLI 核心 | 版本不匹配 | 把 CLI 和插件都升级到最新 |
这篇文章从头到尾把 OpenCode 的安装、配置、模型选择、VSCode 集成、代码修改、Skills 和常见报错都过了一遍。最后我再补一个自己的心得：别指望 AI 一步到位，好的用法是让它先给出方案框架，你再逐步修正方向。我见过太多人一上来就让 AI 直接改大文件，改完满屏报错，最后反而觉得工具不好用。实际上，OpenCode 这类 Agent 工具最适合的用法，是把它当成一个可以随时讨论方案、快速出草稿、帮忙跑命令的结对程序员，而不是一个能完全交付项目的"黑箱"。你给它的指令越清晰，它的产出就越可控。
