1. 先搞清楚OpenCode是什么再动手装1.1 它和Claude Code、Codex这些终端AI工具有什么区别如果你之前在终端里用过Claude Code或者Codex CLI那理解OpenCode会非常快。它本质上也是一个跑在终端里的AI编程助手你给它一句自然语言指令它就能读项目代码、改文件、执行命令、提交代码。这类工具这两年发展特别猛几乎成了AI辅助开发的标配形态。但OpenCode的定位和那两家不太一样。Claude Code绑定Anthropic的模型Codex绑定OpenAI的模型而OpenCode更像一个聚合入口它不强制你绑定某一家你可以接Anthropic、OpenAI、Google乃至本地跑的Ollama模型。这一点对国内开发者尤其实际因为不同模型的擅长方向不一样写业务代码用一个模型做架构设计、写测试用例可能另一个模型表现更好。你不需要装多套工具一个OpenCode全搞定想切谁就切谁。另一个值得关注的背景是OpenCode是开源项目不是某个云厂商闭门造车做出来捆住用户的闭环产品。开源意味着社区活跃、迭代快、可以自己改源码做二次集成也意味着它的配置方式和数据存储都比较透明。项目里还引入了AGENTS.md这类工程约定文件和Codex、Claude Code的工作方式打通方便整个团队统一AI协作规范。当然它也不是没有槽点。终端工具的上手门槛天然比图形界面高一点新手第一次跑起来可能连要填什么都不知道另外它背后要接模型就涉及到API Key、额度、免费层这些绕不开的配置问题。正好这些就是本文要一步步拆开讲清楚的东西。1.2 为什么我建议在Windows上折腾OpenCode很多人觉得终端AI编程助手是Mac用户的专利因为不少类似工具对Windows的支持都很敷衍——要么要求必须装WSL要么在PowerShell里跑起来一堆兼容问题。OpenCode在这点上做得比较友好它在Windows原生环境下可以正常运行不需要强行上WSL。这意味着什么意味着你不需要为了一个终端工具去折腾Linux子系统、配置跨文件系统路径、处理Windows和Linux的环境变量差异直接用Windows Terminal加PowerShell就能跑起来。我在日常使用中实测下来OpenCode对Windows的适配整体是比较稳的。命令执行走的是系统默认Shell文件和路径处理也能识别Windows风格的反斜杠路径基本不会出现那种在Mac上正常、切到Windows就报错的情况。对于习惯了Windows生态的开发者这是非常实际的便利。这篇教程的受众也很清楚第一类是完全没接触过终端AI工具的新手我后面会把安装、配置、命令一条条列清楚你照着抄就能跑起来第二类是用过Claude Code或Codex、想换到OpenCode做模型统一管理的老手可以直接跳到你关心的模型配置、指令和进阶用法章节。两种读者的需求都能在这里找到答案。2. Windows安装OpenCode的完整步骤2.1 安装前准备Node.js版本和终端环境检查OpenCode是跑在Node.js运行时上的工具所以安装它的前提是先装好Node.js。这个检查很简单打开Windows Terminal或者PowerShell输入node -v npm -v如果能看到版本号比如 v20.11.1 和 10.2.4说明环境没问题。如果提示“node不是内部或外部命令”那就要先去Node.js官网下载LTS版本安装包一路下一步装好再重新打开终端验证。建议装LTS版本也就是长期支持版稳定性和兼容性都比追新版本的体验好。实测在Node 18、20、22这几个主要版本上跑OpenCode都没出过问题但低于16的旧版本就不要指望了很多现代依赖根本跑不起来。终端方面强烈建议用Windows Terminal别用老的cmd窗口。Windows Terminal对UTF-8字符集、ANSI颜色、快捷键的支持都更好而OpenCode的交互界面大量使用了颜色和特殊字符在cmd里显示可能会乱掉。怎么判断你的Windows Terminal版本正不正常看能不能正常显示中文、有没有标签页功能这两个基础能力满足就没问题。还有一个容易被忽略的点PowerShell的执行策略。Windows默认可能限制脚本执行如果你之前没改过策略首次运行某些工具时会遇到“无法加载文件因为在此系统上禁止运行脚本”的报错。解决办法是用管理员身份打开PowerShell执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这个命令的意思是本机下载的脚本可以运行从网络下载的脚本需要有签名。选CurrentUser作用域只是为了当前用户生效不会影响系统其他用户相对安全。这一步做了之后后续很多工具安装和命令执行都能省掉一堆麻烦。2.2 正式安装npm命令与首次启动验证环境准备好之后安装OpenCode本身其实就一条命令的事。打开终端执行npm install -g opencode-ai-g参数表示全局安装装完之后任意目录下都能直接运行。如果npm默认源下载速度比较慢可以先配置成国内镜像源再执行安装。镜像源配置本身不复杂但要注意操作对象。Windows下查看当前npm源用的是npm config get registry如果这一步返回的是默认官方地址下载依赖的时候会明显慢尤其是OpenCode这种依赖树比较深的项目卡在某个包上好几分钟都是常有的事。建议装之前把npm源切到国内镜像安装速度会快非常多。安装过程中如果看到一大串npm WARN只要不是error级别报错基本不用管继续等它跑完就行。装完验证一下opencode --version能输出版本号就说明安装成功。首次运行只需要在项目目录下直接输入opencode它会进入一个带交互界面的对话模式第一次启动可能会提示你选择要使用的模型提供商或者生成一个默认配置文件。这一步不同的版本界面略有差异但大方向都是引导你完成最基本的身份认证或Provider选择。如果这些都没做先别急接下来我专门讲怎么配置模型提供商一步步把连接打通。2.3 配置环境变量Windows下最容易踩坑的一步OpenCode连接模型提供商时最核心的认证信息是通过环境变量传递的。比如接Anthropic模型需要ANTHROPIC_API_KEY接OpenAI模型需要OPENAI_API_KEY接Ollama本地模型可能还需要设置OLLAMA_BASE_URL。这一步在Windows上很基础但很关键。配置方式有两种。第一种是临时性的只在当前终端窗口生效适合测试和调试$env:ANTHROPIC_API_KEYsk-ant-你的key设置完直接在同一窗口里运行opencode就能识别到这个变量但关掉终端就失效了要重新设置。第二种是永久性的写入用户环境变量Windows系统设置里找到“编辑账户的环境变量”新建变量名和变量值确定保存后重新打开终端就生效了。也可以在PowerShell里用setx命令写setx ANTHROPIC_API_KEY sk-ant-你的key这里有个需要注意的坑setx设置的是注册表里保存的用户环境变量当前已经打开的所有终端窗口不会立即读取到新值只有新开的终端窗口才能读到。如果你setx完之后在当前窗口运行opencode发现识别不到key不要怀疑自己写错了新开一个终端再试就行。还有一个配置上的细节如果你同时配置了多个Provider的密钥OpenCode在启动时会自动探测哪些Provider可用并在模型列表里展示出来。这也就意味着环境变量配置得越全你在OpenCode里能切换的模型范围就越广。3. 连接模型提供商把模型接进来的三种方式3.1 官方免费层先体验再付费的正确姿势任何一个新工具上手第一步永远先试免费额度OpenCode也不例外。OpenCode提供了免费层给用户体验不需要绑定支付方式就能获得少量调用额度这对评估工具好不好用特别重要。但免费层有一个限制条件我在实际使用中遇到多次也看到不少人求助当你用第三方客户端或第三方方式调用OpenCode的免费层接口时会收到类似“error from provider (console): opencodes free tier can only be used from within opencode”的报错。这个报错翻译过来就是免费层额度只能在OpenCode官方环境内使用。也就是说你用OpenCode自带的交互界面跑免费额度正常生效但如果你想绕开客户端、用别的程序去调用同一条免费通道就会被拒绝。这个限制其实挺合理的免费层本身就是官方为了引导用户体验产品而设的自然不能允许被其他工具套壳白嫖。解决方式也很直接回到OpenCode官方客户端环境里使用免费额度或者干脆配置自己的API Key来获取完整、稳定的服务。如果你确实需要在别的环境里调用OpenCode能力那就得走官方提供的付费订阅或API通道这个我后面会讲到。另外要提醒一点免费层通常有速率限制和次数限制如果你在一个对话里疯狂请求、连续跑大任务很容易触发限流。遇到响应变慢或者出现限流提示先停下来缓几分钟再继续硬着头皮重试只会反复触发限制。3.2 自带API Key接入Anthropic、OpenAI等云端模型如果你想要更稳定的体验、更高的调用额度、更快的响应速度那还是要配自己的API Key来做正式接入。这也是OpenCode最核心的用法。以Anthropic为例先去Anthropic官方控制台注册账号创建API Key。创建时建议给Key设置一个备注名方便识别用途。拿到Key之后在Windows环境变量里配置ANTHROPIC_API_KEY或者写进OpenCode的配置文件里。配置完成后重启OpenCode模型列表里就会出现Anthropic系列模型比如Claude相关的几个版本直接选中就能用了。OpenAI也是同样的套路。配置OPENAI_API_KEY环境变量重启后就能在OpenCode里使用OpenAI的模型。要注意的是当前OpenAI和Anthropic的模型定价方式不同、上下文窗口不同、擅长方向也不同。我自己的使用习惯是代码生成和重构优先用Anthropic系模型因为它的代码理解能力和长上下文处理确实有优势而涉及通用问答、JSON生成、结构化数据提取时我会切到OpenAI系模型。这种“多模型搭配干活”的工作流正是OpenCode这类聚合工具最大的价值所在。配置API Key时安全问题怎么强调都不为过。API Key是你的付费凭证泄露了等于别人拿你的钱去跑模型。建议把Key集中保存在环境变量里而不是硬编码到项目配置文件并提交到Git仓库。如果用的Git记得在.gitignore里忽略包含Key的配置文件。万一发现Key疑似泄露第一时间去控制台吊销重建不要心存侥幸。3.3 接本地模型Ollama搭配OpenCode的私有化方案如果你不想把代码和数据发送到云端API或者只是单纯想省点API调用费接本地模型是很好的选择。目前最常用的本地模型运行工具是Ollama它在Windows上有官方安装包装完就是傻瓜式运行。第一步去Ollama官网下载Windows安装包安装完成后打开终端验证一下ollama --version第二步拉一个模型下来。如果你机器配置一般建议先用小参数模型试水比如ollama pull qwen2.5:7b这个命令会从Ollama模型仓库拉取Qwen2.5的7B参数版本大概几个GB的下载量取决于网络状况。想跑更大的模型、追求更好效果的话可以考虑qwen2.5:14b、32b等版本但显存不够的话推理速度会很难看。第三步在OpenCode里配置Ollama连接。一般是通过环境变量设置OLLAMA_BASE_URL默认地址是http://localhost:11434。配置好之后OpenCode的模型列表里就能看到Ollama这个Provider再选中你本地已经拉取的模型就能开聊了。本地模型的优缺点都很明显优点是不花钱、数据不出内网、没有网络波动影响适合个人隐私项目和离线开发环境缺点是模型能力跟云端大模型比还是有不小差距尤其是在复杂代码理解、长逻辑推理方面。我自己用下来的感觉是本地7B模型应付简单的代码补全、格式化、写注释这些琐事绰绰有余但让它独立设计整个模块的架构还是有点勉强。所以我的方案是简单重复劳动切本地模型复杂任务切云端大模型两边互补既省了钱又不降质量。4. 在OpenCode里切换模型实操指南4.1 对话过程中直接切换模型OpenCode的交互界面设计得比较清爽所有常用操作都围绕着命令和快捷键展开。切换模型这个动作在OpenCode里非常轻量。最直接的方式是在交互界面里输入斜杠指令/models输入这个指令后会弹出一个模型选择列表展示所有可用的Provider和对应的模型。用方向键上下选回车确认当前会话就会切换到选中的模型上。切换完成后不需要重启程序也不需要重新初始化上下文直接把后面的问题抛给它就行。这里有一个体验上的细节值得注意切换模型时当前对话的历史记录和上下文不会被清空。也就是说你可以先用A模型聊完一段需求分析然后切换到B模型继续让它实现代码。B模型能看到之前A模型聊过的内容这在workflow里非常有用。比如我用Claude模型讨论清楚了需求细节再切到OpenAI模型让它按GPT的风格产出格式化代码前后衔接无缝。如果你觉得每次输/models太麻烦可以留意一下快捷键设置。OpenCode支持在配置里自定义快捷键社区里也有人把模型切换绑到功能键上按一下就能循环切换模型。这个看个人习惯我在终端里操作频率最高的切换方式是直接用指令因为手指不用离开键盘主区域肌肉记忆形成之后就很快了。4.2 通过配置文件固定默认模型每次进入OpenCode都要手动切换模型久了也会烦。更合理的做法是在配置文件里把默认模型固定下来。OpenCode的配置文件在Windows下通常位于用户主目录下的配置文件夹里。你可以先通过界面操作生成一个默认配置文件再手动编辑。配置格式大致是JSON结构核心内容是指定Provider和模型名。比如我想把默认模型固定成Anthropic的某款模型就在配置文件里指定对应的Provider和model字段保存后重启OpenCode默认就是它了。配置文件里除了可以设置默认模型还能调整很多行为参数比如最大输出令牌数、温度参数等等。我个人的建议是温度参数不要随意调太高写代码场景保持低温度比如0.2到0.4生成结果会更稳定而头脑风暴、文案写作场景可以适度调高温度输出会更有创造性。参数具体调多少还是要根据你自己的使用场景多试几次没有放之四海皆准的数值。另外OpenCode支持按项目维度做差异化配置。你可以在项目根目录放一个项目级的配置文件指定该项目默认使用哪个模型、启用哪些技能。这样一来你在这个项目里跑opencode它自动加载项目配置跑到另一个项目又自动切到那套配置。多项目并行开发时这种隔离能力非常实用省去了频繁手工切换的麻烦。5. 常用指令与快捷键速查5.1 核心斜杠指令这些必须记牢OpenCode的交互界面里有一批内置的斜杠指令类似IRC时代的斜杠命令学会它们就等于掌握了OpenCode的日常操作。最基础的是/help可以查看所有可用指令的说明遇到陌生指令直接查就行/models前面已经讲过负责切换模型/session用来查看和管理当前会话可以新建会话、切换会话记录这个做多任务并行时特别好用/skills管理和查看可用的技能插件/archive可以把当前会话归档保存做阶段性存档很实用。还有一个指令容易被忽略就是/exit。终端用户可能习惯用CtrlC强杀进程但在OpenCode里CtrlC在某些版本可能被用于打断当前AI响应而不是退出程序。想干净利落地退出用/exit更稳妥。如果你不确定当前版本的快捷键映射按/?或者/help查一下就行。这些指令的共性是全部以斜杠开头输入后可以补全。你不需要记住完整的指令拼写输入前几个字母OpenCode会自动联想出候选回车选中即可。这种交互模式对手指友好度很高熟练后基本不需要翻文档。5.2 终端快捷键和输入技巧OpenCode沿用了不少终端编辑器的交互习惯。方向键上下可以翻历史输入多行输入时ShiftEnter可以换行直接回车则发送消息这个设计跟很多聊天软件反着来我第一次用的时候经常误触习惯后反而觉得更顺手因为单行短指令发送更快多行长内容可以随时换行而不会误发。Esc键用来中断当前AI的响应。当你发现AI理解错了需求、或者回答变得冗长跑偏按Esc打断它重新表述你的问题效率反而更高。如果让AI把一段很长的错误回答跑完浪费时间和token不说还容易把你自己的思路带偏。复制粘贴方面Windows Terminal默认CtrlC是复制、CtrlV是粘贴但OpenCode里CtrlC要留给中断场景还是复制场景不同版本有不同映射。最保险的做法是代码块的内容直接用鼠标选中然后用CtrlShiftC复制CtrlShiftV粘贴这是Windows Terminal默认的剪贴板快捷键基本不会和OpenCode内部的按键冲突。5.3 上下文窗口的使用技巧OpenCode对话的上下文窗口是有长度限制的超过限制后会丢失早期对话信息。实际使用中你会发现刚开始聊的时候模型对项目的理解很到位聊了一两个小时后它好像“忘掉”了最开始你交代过的需求。这往往不是模型变笨了而是早期的内容被挤出了上下文窗口。应对方法很简单重要的需求说明、架构约定、技术约束不要只开篇说一遍就指望模型一直记住。可以写进AGENTS.md这个文件里的内容会被持续注入到每次请求的上下文中相当于给AI立了长期记忆。举个例子你可以在项目根目录创建AGENTS.md写上“本项目使用TypeScript严禁使用Any类型所有API必须做好错误处理”那么无论你开多少个新会话AI都会带上这些约束不会因为上下文轮转而遗忘。会话变长、信息开始丢失时最有效的手段是开新会话把关键上下文重新说明一遍。表面上看这像是在重复劳动但新会话的上下文窗口是满的、清亮的模型的理解能力反而比一个塞满历史垃圾的长会话更强。6. 进阶用法Skills、会话归档和更多玩法6.1 Skills技能插件让OpenCode按你的方式工作Skills是OpenCode一个很有想象力的扩展机制。简单理解它类似于给AI配了一套“自定义工作手册”把特定任务的标准作业流程、约束规则、处理模板打包成技能包AI在遇到对应场景时自动加载并遵守。打个比方你希望AI生成前端代码时一律按照你们团队的目录结构、组件命名规范、样式约定来写。你可以把这些规则编写成一个SkillAI在生成代码时就会主动对齐这些规则而不是给你一份通用的、需要你再改一遍的代码。安装和使用Skill的方式主要通过/skills指令或者手动把技能包放入指定目录。社区已经有不少现成的Skill可以借鉴比如代码审查规则、提交信息规范、单元测试生成模板等等。对于团队来说把Skill同步到版本库所有成员共用一套规范AI产出的一致性会有肉眼可见的提升。从实际体验讲Skill用得好不好关键看你对它的定义是否具体。一个写着“请生成高质量的代码”的Skill几乎等于没有但一个写着“所有React组件必须使用函数组件写法样式使用CSS Modules类名遵循BEM规范”的Skill等于直接把你们的代码规范原文封装给了AI效果天差地别。6.2 会话归档与恢复数据去哪了OpenCode支持会话归档功能但很多人不知道归档之后数据去哪了、怎么恢复。实际上OpenCode把本地会话数据保存到了用户目录下的数据文件夹里以项目维度归档格式上做了结构化的记录。为什么要有归档机制我在实际开发中经常遇到这种场景一个上午花了两小时做技术方案调研聊了很多轮产出了不少有价值的信息。如果直接关掉终端这段对话就留在会话列表里躺着了。归档的意义在于你可以把“已完成”的会话打包存好不再占用当前活跃会话列表后续想回顾时再解档查阅。如果你需要把某段对话记录分享给同事或者迁移到另一台机器直接在数据文件夹里找到对应的会话记录文件即可文件是普通磁盘文件可以直接复制带走。但要注意归档文件不要随便删除删掉之后OpenCode就找不到那段历史记录了。数据安全方面OpenCode的本地数据默认留在本机不会主动上传你的对话记录对于重视代码隐私的团队这一点很重要。6.3 和VSCode配合桌面端工作流的扩展OpenCode本质是终端工具但它可以很方便地和VSCode集成。最常见的打开方式是在VSCode的终端面板里直接跑opencode旁边就是编辑器AI生成的代码可以直接手动复制到文件里或者配合VSCode自带的多光标编辑快速套用。如果你有VSCode的OpenCode相关扩展还能在侧边栏直接启动OpenCode会话省去每次敲命令的功夫。另外OpenCode不止跑在终端里官方也提供了桌面客户端形态和一些SDK级的能力方便开发者把它嵌入到自己的工作台工具里。如果你想要更图形化的操作体验桌面客户端的渲染和交互会更友好一些。但以我个人的使用习惯来说终端形态依然是最顺手的因为所有操作都可以用键盘完成不需要在鼠标和键盘之间来回切换。6.4 GO套餐和商业化订阅什么时候值得付费前面提到OpenCode有免费层但免费层的额度和限制摆在那里对高频深度用户来说肯定不够。OpenCode官方提供了付费订阅套餐大家通常叫它GO套餐。购买之后额度提升、限流减少、稳定性更高最重要的是能解锁在官方环境之外调用能力的方式解决前面提到的“free tier can only be used from within opencode”这类限制。什么时候值得付费我的判断标准很简单如果你每周使用OpenCode超过5个小时或者你已经明确感受到免费层限流严重影响工作节奏了那就可以考虑了。付费订阅本质上买的是时间和稳定对全职开发者来说频繁被限流打断的代价是远高于订阅费的。如果是学生或者轻度尝鲜用户免费层玩一两个月绰绰有余没必要急着付费。无论免费还是收费有一点要始终放在心上AI生成的代码务必人工审查后再合入这跟你用哪个模型、付不付费没有关系这是工程责任问题。7. 常见问题与排查手册7.1 安装类问题npm安装时卡住不动多半是网络问题导致依赖下载缓慢。检查npm源是否已设置为国内镜像确认后再重试安装。opencode命令不是内部或外部命令npm全局包安装目录没有加入PATH。排查办法是先执行npm config get prefix看全局安装路径再用Windows系统设置把该路径追加到用户环境变量PATH里。设置完成后必须重新打开终端才能生效。PowerShell禁止运行脚本这是Windows默认执行策略导致的按2.1节提到的Set-ExecutionPolicy RemoteSigned -Scope CurrentUser处理即可。7.2 模型连接类问题提示无法连接到Provider优先排查环境变量是否正确设置、网络是否连通。记住环境变量修改后要新开终端窗口才生效这是一个极高的错误概率来源。提示error from provider (console): opencodes free tier can only be used from within opencode这个报错的原因和解决办法我在3.1节已经说得比较透了。核心就一句免费层只能在OpenCode官方环境内使用。要么回到官方客户端环境使用要么配置自己的API Key来获得完整的服务能力。模型响应超时或无响应先看是否是免费层限流再参考具体的网络原因。换用自建API Key通常能规避大部分稳定性问题。7.3 使用体验类问题中文输出乱码Windows终端编码问题。在Windows Terminal设置里把默认编码切到UTF-8或者检查系统区域设置的“Beta版使用Unicode UTF-8提供全球语言支持”选项是否启用。这个选项改了之后需要重启系统才能全局生效。长对话变“笨”上下文窗口溢出带来的正常表现不是故障。按5.3节的方法把关键约束写进AGENTS.md必要时开新会话重组上下文。快捷键失灵不同版本OpenCode对快捷键的默认映射有差异。用/help或/?查一下当前版本的快捷键说明或者在配置文件里重新绑定。还有一个排查思路值得推广所有终端工具出问题时重启永远是第一顺位的动作OpenCode也不例外。很多临时性的状态异常比如缓存错乱、进程残留、端口占用一个干净的重启就能解决。如果你尽早习惯了重启用排除法排查路径会短很多。如果重启无效再逐级深入排查配置、网络、权限这些因素。另外平时用OpenCode养成的建议是每天工作结束前把重要会话归档一次。归档操作很简单但日积月累下来你的历史会话会非常规整找起以前的讨论记录来省时省力这个习惯的关键好处要亲身体会才会重视起来。 Windows安装OpenCode终端AI助手全攻略：从零配置到多模型切换
1. 先搞清楚OpenCode是什么再动手装1.1 它和Claude Code、Codex这些终端AI工具有什么区别如果你之前在终端里用过Claude Code或者Codex CLI那理解OpenCode会非常快。它本质上也是一个跑在终端里的AI编程助手你给它一句自然语言指令它就能读项目代码、改文件、执行命令、提交代码。这类工具这两年发展特别猛几乎成了AI辅助开发的标配形态。但OpenCode的定位和那两家不太一样。Claude Code绑定Anthropic的模型Codex绑定OpenAI的模型而OpenCode更像一个聚合入口它不强制你绑定某一家你可以接Anthropic、OpenAI、Google乃至本地跑的Ollama模型。这一点对国内开发者尤其实际因为不同模型的擅长方向不一样写业务代码用一个模型做架构设计、写测试用例可能另一个模型表现更好。你不需要装多套工具一个OpenCode全搞定想切谁就切谁。另一个值得关注的背景是OpenCode是开源项目不是某个云厂商闭门造车做出来捆住用户的闭环产品。开源意味着社区活跃、迭代快、可以自己改源码做二次集成也意味着它的配置方式和数据存储都比较透明。项目里还引入了AGENTS.md这类工程约定文件和Codex、Claude Code的工作方式打通方便整个团队统一AI协作规范。当然它也不是没有槽点。终端工具的上手门槛天然比图形界面高一点新手第一次跑起来可能连要填什么都不知道另外它背后要接模型就涉及到API Key、额度、免费层这些绕不开的配置问题。正好这些就是本文要一步步拆开讲清楚的东西。1.2 为什么我建议在Windows上折腾OpenCode很多人觉得终端AI编程助手是Mac用户的专利因为不少类似工具对Windows的支持都很敷衍——要么要求必须装WSL要么在PowerShell里跑起来一堆兼容问题。OpenCode在这点上做得比较友好它在Windows原生环境下可以正常运行不需要强行上WSL。这意味着什么意味着你不需要为了一个终端工具去折腾Linux子系统、配置跨文件系统路径、处理Windows和Linux的环境变量差异直接用Windows Terminal加PowerShell就能跑起来。我在日常使用中实测下来OpenCode对Windows的适配整体是比较稳的。命令执行走的是系统默认Shell文件和路径处理也能识别Windows风格的反斜杠路径基本不会出现那种在Mac上正常、切到Windows就报错的情况。对于习惯了Windows生态的开发者这是非常实际的便利。这篇教程的受众也很清楚第一类是完全没接触过终端AI工具的新手我后面会把安装、配置、命令一条条列清楚你照着抄就能跑起来第二类是用过Claude Code或Codex、想换到OpenCode做模型统一管理的老手可以直接跳到你关心的模型配置、指令和进阶用法章节。两种读者的需求都能在这里找到答案。2. Windows安装OpenCode的完整步骤2.1 安装前准备Node.js版本和终端环境检查OpenCode是跑在Node.js运行时上的工具所以安装它的前提是先装好Node.js。这个检查很简单打开Windows Terminal或者PowerShell输入node -v npm -v如果能看到版本号比如 v20.11.1 和 10.2.4说明环境没问题。如果提示“node不是内部或外部命令”那就要先去Node.js官网下载LTS版本安装包一路下一步装好再重新打开终端验证。建议装LTS版本也就是长期支持版稳定性和兼容性都比追新版本的体验好。实测在Node 18、20、22这几个主要版本上跑OpenCode都没出过问题但低于16的旧版本就不要指望了很多现代依赖根本跑不起来。终端方面强烈建议用Windows Terminal别用老的cmd窗口。Windows Terminal对UTF-8字符集、ANSI颜色、快捷键的支持都更好而OpenCode的交互界面大量使用了颜色和特殊字符在cmd里显示可能会乱掉。怎么判断你的Windows Terminal版本正不正常看能不能正常显示中文、有没有标签页功能这两个基础能力满足就没问题。还有一个容易被忽略的点PowerShell的执行策略。Windows默认可能限制脚本执行如果你之前没改过策略首次运行某些工具时会遇到“无法加载文件因为在此系统上禁止运行脚本”的报错。解决办法是用管理员身份打开PowerShell执行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser这个命令的意思是本机下载的脚本可以运行从网络下载的脚本需要有签名。选CurrentUser作用域只是为了当前用户生效不会影响系统其他用户相对安全。这一步做了之后后续很多工具安装和命令执行都能省掉一堆麻烦。2.2 正式安装npm命令与首次启动验证环境准备好之后安装OpenCode本身其实就一条命令的事。打开终端执行npm install -g opencode-ai-g参数表示全局安装装完之后任意目录下都能直接运行。如果npm默认源下载速度比较慢可以先配置成国内镜像源再执行安装。镜像源配置本身不复杂但要注意操作对象。Windows下查看当前npm源用的是npm config get registry如果这一步返回的是默认官方地址下载依赖的时候会明显慢尤其是OpenCode这种依赖树比较深的项目卡在某个包上好几分钟都是常有的事。建议装之前把npm源切到国内镜像安装速度会快非常多。安装过程中如果看到一大串npm WARN只要不是error级别报错基本不用管继续等它跑完就行。装完验证一下opencode --version能输出版本号就说明安装成功。首次运行只需要在项目目录下直接输入opencode它会进入一个带交互界面的对话模式第一次启动可能会提示你选择要使用的模型提供商或者生成一个默认配置文件。这一步不同的版本界面略有差异但大方向都是引导你完成最基本的身份认证或Provider选择。如果这些都没做先别急接下来我专门讲怎么配置模型提供商一步步把连接打通。2.3 配置环境变量Windows下最容易踩坑的一步OpenCode连接模型提供商时最核心的认证信息是通过环境变量传递的。比如接Anthropic模型需要ANTHROPIC_API_KEY接OpenAI模型需要OPENAI_API_KEY接Ollama本地模型可能还需要设置OLLAMA_BASE_URL。这一步在Windows上很基础但很关键。配置方式有两种。第一种是临时性的只在当前终端窗口生效适合测试和调试$env:ANTHROPIC_API_KEYsk-ant-你的key设置完直接在同一窗口里运行opencode就能识别到这个变量但关掉终端就失效了要重新设置。第二种是永久性的写入用户环境变量Windows系统设置里找到“编辑账户的环境变量”新建变量名和变量值确定保存后重新打开终端就生效了。也可以在PowerShell里用setx命令写setx ANTHROPIC_API_KEY sk-ant-你的key这里有个需要注意的坑setx设置的是注册表里保存的用户环境变量当前已经打开的所有终端窗口不会立即读取到新值只有新开的终端窗口才能读到。如果你setx完之后在当前窗口运行opencode发现识别不到key不要怀疑自己写错了新开一个终端再试就行。还有一个配置上的细节如果你同时配置了多个Provider的密钥OpenCode在启动时会自动探测哪些Provider可用并在模型列表里展示出来。这也就意味着环境变量配置得越全你在OpenCode里能切换的模型范围就越广。3. 连接模型提供商把模型接进来的三种方式3.1 官方免费层先体验再付费的正确姿势任何一个新工具上手第一步永远先试免费额度OpenCode也不例外。OpenCode提供了免费层给用户体验不需要绑定支付方式就能获得少量调用额度这对评估工具好不好用特别重要。但免费层有一个限制条件我在实际使用中遇到多次也看到不少人求助当你用第三方客户端或第三方方式调用OpenCode的免费层接口时会收到类似“error from provider (console): opencodes free tier can only be used from within opencode”的报错。这个报错翻译过来就是免费层额度只能在OpenCode官方环境内使用。也就是说你用OpenCode自带的交互界面跑免费额度正常生效但如果你想绕开客户端、用别的程序去调用同一条免费通道就会被拒绝。这个限制其实挺合理的免费层本身就是官方为了引导用户体验产品而设的自然不能允许被其他工具套壳白嫖。解决方式也很直接回到OpenCode官方客户端环境里使用免费额度或者干脆配置自己的API Key来获取完整、稳定的服务。如果你确实需要在别的环境里调用OpenCode能力那就得走官方提供的付费订阅或API通道这个我后面会讲到。另外要提醒一点免费层通常有速率限制和次数限制如果你在一个对话里疯狂请求、连续跑大任务很容易触发限流。遇到响应变慢或者出现限流提示先停下来缓几分钟再继续硬着头皮重试只会反复触发限制。3.2 自带API Key接入Anthropic、OpenAI等云端模型如果你想要更稳定的体验、更高的调用额度、更快的响应速度那还是要配自己的API Key来做正式接入。这也是OpenCode最核心的用法。以Anthropic为例先去Anthropic官方控制台注册账号创建API Key。创建时建议给Key设置一个备注名方便识别用途。拿到Key之后在Windows环境变量里配置ANTHROPIC_API_KEY或者写进OpenCode的配置文件里。配置完成后重启OpenCode模型列表里就会出现Anthropic系列模型比如Claude相关的几个版本直接选中就能用了。OpenAI也是同样的套路。配置OPENAI_API_KEY环境变量重启后就能在OpenCode里使用OpenAI的模型。要注意的是当前OpenAI和Anthropic的模型定价方式不同、上下文窗口不同、擅长方向也不同。我自己的使用习惯是代码生成和重构优先用Anthropic系模型因为它的代码理解能力和长上下文处理确实有优势而涉及通用问答、JSON生成、结构化数据提取时我会切到OpenAI系模型。这种“多模型搭配干活”的工作流正是OpenCode这类聚合工具最大的价值所在。配置API Key时安全问题怎么强调都不为过。API Key是你的付费凭证泄露了等于别人拿你的钱去跑模型。建议把Key集中保存在环境变量里而不是硬编码到项目配置文件并提交到Git仓库。如果用的Git记得在.gitignore里忽略包含Key的配置文件。万一发现Key疑似泄露第一时间去控制台吊销重建不要心存侥幸。3.3 接本地模型Ollama搭配OpenCode的私有化方案如果你不想把代码和数据发送到云端API或者只是单纯想省点API调用费接本地模型是很好的选择。目前最常用的本地模型运行工具是Ollama它在Windows上有官方安装包装完就是傻瓜式运行。第一步去Ollama官网下载Windows安装包安装完成后打开终端验证一下ollama --version第二步拉一个模型下来。如果你机器配置一般建议先用小参数模型试水比如ollama pull qwen2.5:7b这个命令会从Ollama模型仓库拉取Qwen2.5的7B参数版本大概几个GB的下载量取决于网络状况。想跑更大的模型、追求更好效果的话可以考虑qwen2.5:14b、32b等版本但显存不够的话推理速度会很难看。第三步在OpenCode里配置Ollama连接。一般是通过环境变量设置OLLAMA_BASE_URL默认地址是http://localhost:11434。配置好之后OpenCode的模型列表里就能看到Ollama这个Provider再选中你本地已经拉取的模型就能开聊了。本地模型的优缺点都很明显优点是不花钱、数据不出内网、没有网络波动影响适合个人隐私项目和离线开发环境缺点是模型能力跟云端大模型比还是有不小差距尤其是在复杂代码理解、长逻辑推理方面。我自己用下来的感觉是本地7B模型应付简单的代码补全、格式化、写注释这些琐事绰绰有余但让它独立设计整个模块的架构还是有点勉强。所以我的方案是简单重复劳动切本地模型复杂任务切云端大模型两边互补既省了钱又不降质量。4. 在OpenCode里切换模型实操指南4.1 对话过程中直接切换模型OpenCode的交互界面设计得比较清爽所有常用操作都围绕着命令和快捷键展开。切换模型这个动作在OpenCode里非常轻量。最直接的方式是在交互界面里输入斜杠指令/models输入这个指令后会弹出一个模型选择列表展示所有可用的Provider和对应的模型。用方向键上下选回车确认当前会话就会切换到选中的模型上。切换完成后不需要重启程序也不需要重新初始化上下文直接把后面的问题抛给它就行。这里有一个体验上的细节值得注意切换模型时当前对话的历史记录和上下文不会被清空。也就是说你可以先用A模型聊完一段需求分析然后切换到B模型继续让它实现代码。B模型能看到之前A模型聊过的内容这在workflow里非常有用。比如我用Claude模型讨论清楚了需求细节再切到OpenAI模型让它按GPT的风格产出格式化代码前后衔接无缝。如果你觉得每次输/models太麻烦可以留意一下快捷键设置。OpenCode支持在配置里自定义快捷键社区里也有人把模型切换绑到功能键上按一下就能循环切换模型。这个看个人习惯我在终端里操作频率最高的切换方式是直接用指令因为手指不用离开键盘主区域肌肉记忆形成之后就很快了。4.2 通过配置文件固定默认模型每次进入OpenCode都要手动切换模型久了也会烦。更合理的做法是在配置文件里把默认模型固定下来。OpenCode的配置文件在Windows下通常位于用户主目录下的配置文件夹里。你可以先通过界面操作生成一个默认配置文件再手动编辑。配置格式大致是JSON结构核心内容是指定Provider和模型名。比如我想把默认模型固定成Anthropic的某款模型就在配置文件里指定对应的Provider和model字段保存后重启OpenCode默认就是它了。配置文件里除了可以设置默认模型还能调整很多行为参数比如最大输出令牌数、温度参数等等。我个人的建议是温度参数不要随意调太高写代码场景保持低温度比如0.2到0.4生成结果会更稳定而头脑风暴、文案写作场景可以适度调高温度输出会更有创造性。参数具体调多少还是要根据你自己的使用场景多试几次没有放之四海皆准的数值。另外OpenCode支持按项目维度做差异化配置。你可以在项目根目录放一个项目级的配置文件指定该项目默认使用哪个模型、启用哪些技能。这样一来你在这个项目里跑opencode它自动加载项目配置跑到另一个项目又自动切到那套配置。多项目并行开发时这种隔离能力非常实用省去了频繁手工切换的麻烦。5. 常用指令与快捷键速查5.1 核心斜杠指令这些必须记牢OpenCode的交互界面里有一批内置的斜杠指令类似IRC时代的斜杠命令学会它们就等于掌握了OpenCode的日常操作。最基础的是/help可以查看所有可用指令的说明遇到陌生指令直接查就行/models前面已经讲过负责切换模型/session用来查看和管理当前会话可以新建会话、切换会话记录这个做多任务并行时特别好用/skills管理和查看可用的技能插件/archive可以把当前会话归档保存做阶段性存档很实用。还有一个指令容易被忽略就是/exit。终端用户可能习惯用CtrlC强杀进程但在OpenCode里CtrlC在某些版本可能被用于打断当前AI响应而不是退出程序。想干净利落地退出用/exit更稳妥。如果你不确定当前版本的快捷键映射按/?或者/help查一下就行。这些指令的共性是全部以斜杠开头输入后可以补全。你不需要记住完整的指令拼写输入前几个字母OpenCode会自动联想出候选回车选中即可。这种交互模式对手指友好度很高熟练后基本不需要翻文档。5.2 终端快捷键和输入技巧OpenCode沿用了不少终端编辑器的交互习惯。方向键上下可以翻历史输入多行输入时ShiftEnter可以换行直接回车则发送消息这个设计跟很多聊天软件反着来我第一次用的时候经常误触习惯后反而觉得更顺手因为单行短指令发送更快多行长内容可以随时换行而不会误发。Esc键用来中断当前AI的响应。当你发现AI理解错了需求、或者回答变得冗长跑偏按Esc打断它重新表述你的问题效率反而更高。如果让AI把一段很长的错误回答跑完浪费时间和token不说还容易把你自己的思路带偏。复制粘贴方面Windows Terminal默认CtrlC是复制、CtrlV是粘贴但OpenCode里CtrlC要留给中断场景还是复制场景不同版本有不同映射。最保险的做法是代码块的内容直接用鼠标选中然后用CtrlShiftC复制CtrlShiftV粘贴这是Windows Terminal默认的剪贴板快捷键基本不会和OpenCode内部的按键冲突。5.3 上下文窗口的使用技巧OpenCode对话的上下文窗口是有长度限制的超过限制后会丢失早期对话信息。实际使用中你会发现刚开始聊的时候模型对项目的理解很到位聊了一两个小时后它好像“忘掉”了最开始你交代过的需求。这往往不是模型变笨了而是早期的内容被挤出了上下文窗口。应对方法很简单重要的需求说明、架构约定、技术约束不要只开篇说一遍就指望模型一直记住。可以写进AGENTS.md这个文件里的内容会被持续注入到每次请求的上下文中相当于给AI立了长期记忆。举个例子你可以在项目根目录创建AGENTS.md写上“本项目使用TypeScript严禁使用Any类型所有API必须做好错误处理”那么无论你开多少个新会话AI都会带上这些约束不会因为上下文轮转而遗忘。会话变长、信息开始丢失时最有效的手段是开新会话把关键上下文重新说明一遍。表面上看这像是在重复劳动但新会话的上下文窗口是满的、清亮的模型的理解能力反而比一个塞满历史垃圾的长会话更强。6. 进阶用法Skills、会话归档和更多玩法6.1 Skills技能插件让OpenCode按你的方式工作Skills是OpenCode一个很有想象力的扩展机制。简单理解它类似于给AI配了一套“自定义工作手册”把特定任务的标准作业流程、约束规则、处理模板打包成技能包AI在遇到对应场景时自动加载并遵守。打个比方你希望AI生成前端代码时一律按照你们团队的目录结构、组件命名规范、样式约定来写。你可以把这些规则编写成一个SkillAI在生成代码时就会主动对齐这些规则而不是给你一份通用的、需要你再改一遍的代码。安装和使用Skill的方式主要通过/skills指令或者手动把技能包放入指定目录。社区已经有不少现成的Skill可以借鉴比如代码审查规则、提交信息规范、单元测试生成模板等等。对于团队来说把Skill同步到版本库所有成员共用一套规范AI产出的一致性会有肉眼可见的提升。从实际体验讲Skill用得好不好关键看你对它的定义是否具体。一个写着“请生成高质量的代码”的Skill几乎等于没有但一个写着“所有React组件必须使用函数组件写法样式使用CSS Modules类名遵循BEM规范”的Skill等于直接把你们的代码规范原文封装给了AI效果天差地别。6.2 会话归档与恢复数据去哪了OpenCode支持会话归档功能但很多人不知道归档之后数据去哪了、怎么恢复。实际上OpenCode把本地会话数据保存到了用户目录下的数据文件夹里以项目维度归档格式上做了结构化的记录。为什么要有归档机制我在实际开发中经常遇到这种场景一个上午花了两小时做技术方案调研聊了很多轮产出了不少有价值的信息。如果直接关掉终端这段对话就留在会话列表里躺着了。归档的意义在于你可以把“已完成”的会话打包存好不再占用当前活跃会话列表后续想回顾时再解档查阅。如果你需要把某段对话记录分享给同事或者迁移到另一台机器直接在数据文件夹里找到对应的会话记录文件即可文件是普通磁盘文件可以直接复制带走。但要注意归档文件不要随便删除删掉之后OpenCode就找不到那段历史记录了。数据安全方面OpenCode的本地数据默认留在本机不会主动上传你的对话记录对于重视代码隐私的团队这一点很重要。6.3 和VSCode配合桌面端工作流的扩展OpenCode本质是终端工具但它可以很方便地和VSCode集成。最常见的打开方式是在VSCode的终端面板里直接跑opencode旁边就是编辑器AI生成的代码可以直接手动复制到文件里或者配合VSCode自带的多光标编辑快速套用。如果你有VSCode的OpenCode相关扩展还能在侧边栏直接启动OpenCode会话省去每次敲命令的功夫。另外OpenCode不止跑在终端里官方也提供了桌面客户端形态和一些SDK级的能力方便开发者把它嵌入到自己的工作台工具里。如果你想要更图形化的操作体验桌面客户端的渲染和交互会更友好一些。但以我个人的使用习惯来说终端形态依然是最顺手的因为所有操作都可以用键盘完成不需要在鼠标和键盘之间来回切换。6.4 GO套餐和商业化订阅什么时候值得付费前面提到OpenCode有免费层但免费层的额度和限制摆在那里对高频深度用户来说肯定不够。OpenCode官方提供了付费订阅套餐大家通常叫它GO套餐。购买之后额度提升、限流减少、稳定性更高最重要的是能解锁在官方环境之外调用能力的方式解决前面提到的“free tier can only be used from within opencode”这类限制。什么时候值得付费我的判断标准很简单如果你每周使用OpenCode超过5个小时或者你已经明确感受到免费层限流严重影响工作节奏了那就可以考虑了。付费订阅本质上买的是时间和稳定对全职开发者来说频繁被限流打断的代价是远高于订阅费的。如果是学生或者轻度尝鲜用户免费层玩一两个月绰绰有余没必要急着付费。无论免费还是收费有一点要始终放在心上AI生成的代码务必人工审查后再合入这跟你用哪个模型、付不付费没有关系这是工程责任问题。7. 常见问题与排查手册7.1 安装类问题npm安装时卡住不动多半是网络问题导致依赖下载缓慢。检查npm源是否已设置为国内镜像确认后再重试安装。opencode命令不是内部或外部命令npm全局包安装目录没有加入PATH。排查办法是先执行npm config get prefix看全局安装路径再用Windows系统设置把该路径追加到用户环境变量PATH里。设置完成后必须重新打开终端才能生效。PowerShell禁止运行脚本这是Windows默认执行策略导致的按2.1节提到的Set-ExecutionPolicy RemoteSigned -Scope CurrentUser处理即可。7.2 模型连接类问题提示无法连接到Provider优先排查环境变量是否正确设置、网络是否连通。记住环境变量修改后要新开终端窗口才生效这是一个极高的错误概率来源。提示error from provider (console): opencodes free tier can only be used from within opencode这个报错的原因和解决办法我在3.1节已经说得比较透了。核心就一句免费层只能在OpenCode官方环境内使用。要么回到官方客户端环境使用要么配置自己的API Key来获得完整的服务能力。模型响应超时或无响应先看是否是免费层限流再参考具体的网络原因。换用自建API Key通常能规避大部分稳定性问题。7.3 使用体验类问题中文输出乱码Windows终端编码问题。在Windows Terminal设置里把默认编码切到UTF-8或者检查系统区域设置的“Beta版使用Unicode UTF-8提供全球语言支持”选项是否启用。这个选项改了之后需要重启系统才能全局生效。长对话变“笨”上下文窗口溢出带来的正常表现不是故障。按5.3节的方法把关键约束写进AGENTS.md必要时开新会话重组上下文。快捷键失灵不同版本OpenCode对快捷键的默认映射有差异。用/help或/?查一下当前版本的快捷键说明或者在配置文件里重新绑定。还有一个排查思路值得推广所有终端工具出问题时重启永远是第一顺位的动作OpenCode也不例外。很多临时性的状态异常比如缓存错乱、进程残留、端口占用一个干净的重启就能解决。如果你尽早习惯了重启用排除法排查路径会短很多。如果重启无效再逐级深入排查配置、网络、权限这些因素。另外平时用OpenCode养成的建议是每天工作结束前把重要会话归档一次。归档操作很简单但日积月累下来你的历史会话会非常规整找起以前的讨论记录来省时省力这个习惯的关键好处要亲身体会才会重视起来。