OpenCode 这阵子在 AI 编程圈子里热度涨得很快很多人直接把它当成 Claude Code 的平替来用。我用了一段时间之后个人感受是它比我想象中“更能干活”不仅能在终端里聊天还能自己读项目结构、改文件、跑命令甚至配合技能包完成重复性工程任务。这篇教程按 Windows 环境来写因为 Windows 上折腾终端工具通常比 macOS 多一些细节。内容会覆盖从零安装、连接模型提供商、切换模型、常用指令到进阶玩法尽量做到保姆级跟着操作就能跑通。1. 先搞明白 OpenCode 是什么终端 AI 编程工具里的“实干派”1.1 它不是一个聊天框而是一个会自己动手的 AgentOpenCode 是 SST 团队就是做 serverless 框架那个团队开源的一个终端 AI 编程 Agent底层基于 Node.js/TypeScript主程序是一个带 TUI终端界面的命令行工具。和 ChatGPT 网页版那种“你问我答”不同你在 OpenCode 里给它一个任务它会自己去读项目的目录结构、打开相关文件、分析依赖关系然后直接动手改写代码改完还会告诉你它动了哪些文件、为什么这么改。它的定位和 Anthropic 的 Claude Code 非常接近但因为是开源项目模型层完全解耦你可以接 Anthropic、OpenAI也可以接本地 Ollama 模型甚至可以在同一个会话里随时换模型这就解决了很多人“一个模型不够用”的痛点。1.2 和 Claude Code、Cursor、Codex 相比它的差异化在哪很多人会拿 OpenCode 跟这几类工具对比。我的使用感受是工具形态最突出的特点适合场景CursorIDE 插件式编辑器内联补全强日常在编辑器里开发Claude Code终端 TUIClaude 生态原生能力全深度使用 Anthropic 模型Codex终端/桌面OpenAI 系模型为主习惯 OpenAI 模型的人OpenCode终端 TUI开源、模型多供应商、可编程配置喜欢终端操作、想自由切换模型的人OpenCode 最打动我的一点是“模型提供商随意切换”这个设计。它把所有模型抽象成统一的 provider 概念Anthropic、OpenAI、Ollama 本地模型可以共存你在/models里选一下就行不需要为每个模型单独装一个工具。1.3 适合什么样的人用以及不适合什么场景如果你平时就在终端里用 git、用编辑器命令行工具那 OpenCode 的上手成本会非常低如果你完全没接触过终端也不用怕Windows 下按我下面这套流程走半小时内能跑通。它不适合的场景也有比如你只想要一个类似 Cursor 的补全插件那 IDE 里的 AI 插件体验更顺如果项目涉及大量图形化调试比如前端可视化页面的样式微调终端 Agent 仍然不如直接开编辑器来得直观。好概念说完下面进入正题Windows 安装。2. Windows 安装三步走终端准备、执行安装、首次启动2.1 把终端环境整利索Windows Terminal PowerShell 7OpenCode 是终端工具Windows 自带的老式 cmd 或 Windows PowerShell 5.1 能用但体验打折尤其是有时候中文乱码、快捷键失灵。我建议先装 Windows Terminal微软商店直接搜免费再装 PowerShell 7winget 一行搞定。装完之后在 Windows Terminal 的标签页下拉菜单里选择 PowerShell 7 作为默认终端。winget install Microsoft.WindowsTerminal winget install Microsoft.PowerShell这一步不是必须但能让后面的操作顺畅很多。至少也要保证能打开一个正常的 PowerShell 窗口。2.2 三种安装方式推荐第一种OpenCode 官方在 Windows 上推荐用 PowerShell 脚本安装。打开 PowerShell 7执行irm https://opencode.ai/install.ps1 | iexirm是 Invoke-RestMethod 的简写iex是 Invoke-Expression合起来就是“下载安装脚本并执行”。脚本会把 opencode.exe 装到你的用户目录下并自动加入 PATH。如果你之前装过 Node.js也可以走 npm 全局安装npm install -g opencode-ai还有一种是下载官方桌面版安装包适合不常用终端的人但桌面版本质上也是包了一层终端界面想体验完整 TUI还是命令行版本更原汁原味。装完验证一下opencode --version如果提示“找不到命令”大概率是 PATH 没生效重开一个终端窗口再试还是不行就检查安装目录脚本安装一般在%USERPROFILE%\.opencode\binnpm 全局安装在 npm 的 global bin 目录手动把目录加到环境变量 PATH 里。2.3 首次启动和登录完成第一次对话安装完后进入你的项目目录再启动cd D:\projects\my-app opencode首次启动时OpenCode 可能会请求读取文件、执行命令之类的权限并且如果检测到你还没有登录会在界面上提示你先跑opencode auth login。opencode auth login这个命令会列出所有支持的模型提供商包括 OpenCode Go、Anthropic、OpenAI、Google 等。选择你想用的跟着提示走大部分是浏览器授权OpenCode Go 用 GitHub 账号登录即可。登录完回到 TUI在输入框里敲第一句话比如“介绍一下这个项目的结构”回车。如果它开始回复说明整个链路已经通了。2.4 安装后马上要做的两件事默认模型和主题跑通之后我先建议你打开配置文件看一眼。OpenCode 的全局配置文件在C:\Users\你的用户名\.config\opencode\opencode.json如果不存在就手动创建。我最常用的初版配置是这样{ $schema: https://opencode.ai/config.json, model: anthropic/claude-sonnet-4-20250514, theme: opencode }model字段是默认模型theme是 TUI 主题。这样每次进项目不用手动选模型。至于模型 ID 怎么写、provider 怎么配下一节详细讲。3. 连接模型提供商三种方式把“大脑”接进来3.1 provider 是什么模型 ID 的组成规则OpenCode 里所有模型接入都被抽象成 provider模型提供商。模型 ID 的统一格式是provider名/模型名比如anthropic/claude-sonnet-4-20250514、openai/gpt-5。你在/models里看到的就是这个 ID 的可视化列表在配置文件和命令行参数里用的则是完整 ID。搞清楚这个规则后面所有配置都能自己推理出来想在配置里写默认模型就把完整 ID 填进model字段想在命令行里指定模型就用-m参数加完整 ID。3.2 免费方案OpenCode Go 内置额度如果你只是先体验一下我最推荐用 OpenCode Go。这是 OpenCode 官方提供的免费额度通道用 GitHub 账号在 opencode.ai 登录后每天有免费的调用额度具体额度会随官方策略调整。它的接入方式最简单opencode auth login时选择 OpenCode Go 就行不需要任何 API Key。需要注意一点这个免费额度只能在 OpenCode 自己的客户端里使用它的接口地址不是给你拿去给第三方工具用的。很多人把 OpenCode Go 的地址填到别的工具里结果报错这点我放在最后的踩坑章节细说。3.3 API Key 方案Anthropic / OpenAI 环境变量与 auth login如果你有自己的 Anthropic 或 OpenAI API Key两种方式都可以。第一种是直接设置环境变量在 PowerShell 里临时设置$env:ANTHROPIC_API_KEY sk-ant-你的key $env:OPENAI_API_KEY sk-你的key要永久生效用setxsetx ANTHROPIC_API_KEY sk-ant-你的key设置完一定要重新打开终端环境变量才会加载。第二种是用opencode auth login选择 Anthropic 或 OpenAI会走浏览器授权官方推荐这种方式因为 key 不落在 shell 历史里。3.4 本地方案Ollama 跑开源模型没有付费 API 也没关系本地模型完全能用。Windows 上装 Ollama官网下安装包即可然后在 PowerShell 里拉一个适合写代码的模型ollama pull qwen2.5-coder:7b确认 Ollama 在运行Windows 版装完会常驻托盘然后启动 OpenCode打开/models如果版本支持你会看到 Ollama 分组直接选刚拉的模型就能用。如果列表里没有就在 opencode.json 里显式声明{ $schema: https://opencode.ai/config.json, provider: { ollama: { options: { baseURL: http://localhost:11434/v1 }, models: { qwen2.5-coder:7b: { name: Qwen2.5 Coder 7B } } } } }这里的baseURL指向 Ollama 的 OpenAI 兼容端点models里列出你要用的模型。配完重启 OpenCode/models里就能看到了。本地模型的好处是不用担心额度断网也能跑代价是生成速度和质量跟云端大模型还有差距适合做隐私敏感项目的初筛、或者练手。3.5 进阶opencode.json 自定义 provider除了内置的 providerOpenCode 还支持你把任何 OpenAI 兼容的接口接进来。比如公司内部有一个模型服务只要它的接口兼容 OpenAI 格式就可以在 opencode.json 里按 Ollama 的写法配一个自定义 provider改一下baseURL和models即可。这个能力让它不太容易被某个模型厂商绑定也是我愿意长期用它的核心原因。市面上还有一些社区工具比如 cc-switch专门帮你维护多个 provider 配置本质上就是帮你往 opencode.json 里写内容和切换如果你同时接好几个服务可以搜来试试。4. 切换模型在对话里随时换“最强大脑”4.1 /models 选择器provider 分组与模型筛选在 OpenCode 的 TUI 里输入/models回车会弹出模型选择器。左边是 provider 分组Anthropic、OpenAI、OpenCode Go、Ollama 等右边是对应的模型列表。用j/k上下移动回车确认。如果你模型很多选择器还支持输入关键字过滤直接打字就能筛。4.2 对话中直接换模型不用开新会话这是 OpenCode 和很多终端 Agent 差别最大的地方。你在同一个会话里前 20 轮可以用一个便宜的模型做需求分析后面真正写代码时换成更强的模型上下文是连续的不需要复制粘贴对话内容。我实际用下来的经验是一个复杂的重构任务先用轻量模型梳理依赖关系再切换到大模型生成高难度代码整体效率和成本都能兼顾。部分版本还支持用 ShiftTab 在最近用过的模型之间快速循环切换具体以你安装版本的/help提示为准。切换模型不会清空会话但要注意有些供应商之间的功能能力差异很大比如某个模型不支持工具调用切过去之后 Agent 的动作会被限制这时候再切回来即可。4.3 设置默认模型与 run 模式指定模型除了交互式切换两种方式可以固化模型选择。一是配置文件里的model字段设的是默认模型。二是在非交互式运行模式里指定opencode run -m openai/gpt-5 帮我把这个文件里的TODO全部整理到README.md这条命令不走 TUI执行完直接退出适合写脚本、做批处理、接 CI/CD。这也是 OpenCode 比较好用的一个点它不只是一个交互工具还是一个可以通过命令行参数驱动的自动化工具。5. 常用指令清单这些命令撑起了 90% 的日常操作5.1 会话与项目管理类先说和项目、会话生命周期相关的指令作用/help查看所有可用指令和快捷键/init在项目根目录生成 AGENTS.md/sessions查看历史会话列表恢复之前的对话opencode auth logout退出当前账号授权/init值得多说一句。OpenCode 会读项目里的 AGENTS.md 文件来理解项目的约定比如代码风格、目录结构、常用脚本。/init会根据当前项目自动生成一份你也可以手写维护。项目越复杂AGENTS.md 写得越清楚Agent 的表现越好。5.2 结果控制与修改撤回类AI 改代码难免出错这些指令是“后悔药”指令作用/undo撤回最近一次 AI 对文件的修改/redo重新执行被撤回的操作/compact压缩当前会话的上下文减少 token 消耗/compact在长会话里很有用。对话轮次多了上下文窗口不够用的时候输入/compact会把前面的对话浓缩成摘要腾出空间继续干活。注意压缩后细节会有损失如果依赖很细节的上下文先手动把关键信息写进项目笔记里。5.3 生态扩展类agents / skills / mcp / share这四个指令是 OpenCode 的扩展能力入口/agents查看和切换 Agent。Agent 可以理解为“角色设定”不同的 Agent 有不同的系统提示词比如规划型 Agent 只负责拆解任务不写代码执行型 Agent 负责动手。/skills查看和管理技能包。技能包是带 SKILL.md 的脚本目录告诉模型“遇到这类任务时按这个流程做”。/mcp管理 MCP 服务器连接状态。MCPModel Context Protocol是给模型接外部数据的标准协议。/share把当前对话生成一个分享链接或文本方便发给别人复盘。快捷键方面最常用的几个是CtrlC中断当前生成、CtrlD退出 OpenCode部分版本、ShiftTab切换模型部分版本。不确定就/help。6. 进阶玩法Skills、MCP、VSCode、桌面版与数据管理6.1 Skills给 Agent 装“技能包”Skills 是 OpenCode 比较新的功能也是社区很热的话题。一个 Skill 通常是一个目录里面包含SKILL.md描述文件和若干脚本它的作用是让模型在遇到特定任务时按照你定义的流程去执行。比如你可以给项目装一个“代码评审技能”模型每次收到评审请求时会先跑测试、再查 lint、最后按模板输出评审结果。安装方式常见的有两种一是把技能目录放到全局技能目录比如C:\Users\你的用户名\.config\opencode\skills二是把技能放进项目里的.opencode/skills目录只对这个项目生效。装好后在 TUI 里运行/skills刷新并启用。官方和社区都已有一些现成技能包直接在终端里搜“opencode skills”就能找到不少。6.2 MCP把外部工具和数据源接进对话MCP 解决的是“让模型能拿到实时数据”的问题。比如你想让模型查 GitHub Issue、读数据库、操作浏览器都可以通过 MCP 服务器接入。OpenCode 的 MCP 配置写在 opencode.json 里{ mcp: { github: { type: stdio, command: [npx, -y, modelcontextprotocol/server-github], enabled: true } } }配置后在 TUI 里/mcp查看连接状态出现绿色就说明接上了。注意 MCP 服务器是常驻进程别配太多否则每个会话启动都会变慢。6.3 编辑器配合VSCode 扩展与桌面版如果你离不开 VSCodeOpenCode 官方提供了扩展装完可以在编辑器侧边栏直接使用同一个 TUI看代码和调模型不用来回切窗口。桌面版则是从 opencode.ai 下载 Windows 安装包适合更习惯图形界面的人。这几种形态共享同一套数据目录和配置所以你在终端里的会话在桌面版里也能继续。6.4 数据在哪里、归档去哪了、如何备份这个问题被问得很多。OpenCode 的会话数据默认存在用户目录下C:\Users\你的用户名\.local\share\opencode\storage每个会话对应一个 JSONL 文件里面记录了你和模型的每一轮对话、每次文件修改。归档比如 compact 之前的旧内容、或者你主动归档的会话不会凭空消失都还在这些文件里只是不再出现在当前上下文中。想恢复旧会话用/sessions打开。备份整个storage目录即可完整迁移所有历史记录。因为涉及项目代码和对话记录如果项目敏感建议定期手动备份或者把数据目录纳入同步盘。7. Windows 实战踩坑常见错误与解决实录7.1 免费额度报错opencodes free tier can only be used from within opencode这个报错出现的频率很高原文是error from provider (console): opencodes free tier can only be used from within opencode。原因一句话就能说清OpenCode Go 的免费额度是绑定 OpenCode 客户端本身的。如果你把它的接口地址填到了其他工具、或者通过某些第三方服务转出去用服务端检测到请求不是来自 OpenCode 客户端就会拒绝并返回这个错误。解决办法是直接在 OpenCode 里用/models选择 OpenCode Go 下的模型让请求走它自己的客户端通道如果是想在别的工具里接模型就不要用 OpenCode Go改用 Anthropic/OpenAI 的正式 API Key或者接本地 Ollama。7.2 安装脚本被 PowerShell 执行策略拦截执行irm https://opencode.ai/install.ps1 | iex时如果提示“在此系统上禁止运行脚本”是因为 PowerShell 默认执行策略是 Restricted。临时放开当前用户即可Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser改完再执行安装脚本。这只是给当前用户放开本地脚本权限不会影响系统安全级别。7.3 模型列表为空或本地模型连不上/models里空荡荡最常见的有两种情况。一是没有登录也没有配置 API KeyOpenCode 自然不知道有哪些模型可用先跑opencode auth login。二是本地 Ollama 没启动或地址不对用ollama list确认模型已拉取再确认http://localhost:11434能访问。如果自定义了 provider检查baseURL是否写错尤其是最后的/v1路径。7.4 日志、缓存与彻底卸载排查问题时可以看 OpenCode 的日志日志通常也在数据目录下的log子文件夹里。彻底卸载的步骤是先卸载程序npm 安装的就npm uninstall -g opencode-ai脚本安装的手动删除安装目录再删掉配置文件目录和对话数据目录这样机器上不会留下任何痕迹。如果你只是想重置而不是卸载删除storage里的会话文件就能清空历史。最后分享一个我个人的使用习惯现在接到新的小型需求我会先开一个 OpenCode 会话用/init确认项目约束再用免费额度或者本地模型做第一轮分析需要动手写关键模块时切到更强的模型最后用/share把过程和结果发给同事 review。这个流程执行了快两个月最大的感受是“上下文不丢失”比“单次回答质量”对整个项目推进效率的影响更大——而这正是 OpenCode 这种把模型切换、会话管理和数据存储都做在产品内部的设计最值钱的地方。你如果刚在 Windows 上装好建议从最简单的一个小项目试起别一上来就接全套 MCP 和 Skills先让整个链路跑顺再逐步加复杂度。