上个月我干了一件事把一个月几十美元的AI编程订阅给停了换成了一个完全开源、免费的工具——OpenCode。用了一个月我的主力编码工作不但没受影响反而因为这工具的可折腾性把一堆重复劳动都甩给了它。今天就把这套“穷人方案”完完整整复盘一遍怎么装、怎么免费接模型、怎么让它真给你干活、以及我踩过的各种坑。先说清楚一件事OpenCode不是那种云端套壳产品它是一个跑在你终端里的AI编码代理有自己的TUI界面就是终端里的图形交互能直接读写文件、执行命令、调用各种大模型。对“穷人”来说最大的意义在于工具本体免费模型来源你自己说了算——你可以接本地模型一分钱不花也可以接有免费额度的云端API。这篇文章就是写给像我一样不想在AI工具上反复续费的人。1. 先别急着装OpenCode是什么凭什么免费1.1 它和Cursor、Copilot、Claude Code有啥不一样很多人第一次听到OpenCode脑子里首先冒出来的是Cursor、Copilot这类商业产品。说实话它们解决的问题有重叠但使用形态和收费逻辑完全不同。我把这几类工具摆在一起对比过工具形态收费模式模型来源适合人群GitHub CopilotIDE插件按月订阅有免费档但功能受限厂商内置想在IDE里补全/聊天的人Cursor独立IDE订阅制免费额度很少自带模型可配Key愿意迁移编辑器的人Claude Code终端CLI需要Claude API Key/订阅Anthropic模型为主重度终端用户OpenCode终端TUIVS Code插件开源免费任意OpenAI兼容模型/本地模型/官方Go网关想自己掌控模型和成本的用户OpenCode最打动我的地方是它不绑死任何一家模型厂商。你可以今天用本地跑的Qwen明天切到某个有免费额度的云端Gemini后天再切到OpenCode官方的免费网关。模型是你自己的选择而不是工具厂商塞给你的那一个。有人会问那它和Claude Code这种终端型工具比呢我的感受是Claude Code强在Anthropic模型的代码能力但模型绑定太死OpenCode更像一个“模型无关”的终端代理你把什么模型给它它就用什么脑子干活灵活得多。对预算敏感的人来说这种灵活性就是省钱空间。1.2 免费体验的底气来自哪里OpenCode本身是开源项目项目代码在GitHub上遵循开源协议所以你安装、使用、研究它都不需要付费。但“工具免费”只是第一步真正决定成本的是模型。同样一次代码修改请求在不同模型上跑花费可能差出几十倍。好在OpenCode从设计上就支持多种接入方式本地模型通过Ollama这类工具跑开源模型完全离线、完全免费适合隐私敏感和预算为零的场景。自带网关GoOpenCode官方提供了一个模型聚合服务里面有几个免费模型额度注册登录就能用对个人日常开发来说非常够。第三方AI服务OpenAI、Google Gemini、Anthropic这些大厂的API以及国内厂商的开放平台API凡是有免费额度或者低价档的都能配置进去。自建代理/中转如果你公司内部有统一的大模型中转服务同样可以接。说白了OpenCode把“模型接入”这件事做成了标准化的插槽你想往哪个插槽里插什么模型全由你自己定。这不光是省钱的问题还是一个使用哲学的问题你应该拥有选择模型的权利而不是被某个工具捆绑。1.3 什么样的人适合直接上车我自己的经验是OpenCode适合三类人第一类是长期泡在终端里的开发者。你本来就习惯用命令行OpenCode的TUI不会有任何学习负担反而会让你觉得“在终端里聊代码”比切到浏览器还舒服。第二类是用AI写代码但不想被某个订阅套牢的人。你可以随时切换模型供应商哪个便宜用哪个哪个当天免费额度没用完就切哪个。第三类是代码量不大、但各种杂事特别多的人。OpenCode不止能写代码还能写脚本、整理日志、批量改文件、生成文档。我用它干了不少原本要花一上午的杂活后面我会详细说。当然如果你是完全没有编程基础的小白只想点开一个窗口让AI帮你写个完整网站那OpenCode不是最优选它更适合有一定命令行和代码基础的人。这篇教程也会从偏基础的角度带大家走一遍但你至少要会打开终端。2. 从零安装三步让OpenCode在电脑上跑起来2.1 前置环境确认Node版本、Git和终端习惯安装OpenCode之前先确认几样东西。Node.js是必须的OpenCode是基于Node生态构建的建议装Node 18以上版本。在终端里敲node -v如果输出一个版本号比如v20.12.0说明没问题。如果提示找不到node去官网下载LTS版本装一下就行。装完记得重新开一个终端窗口让环境变量生效。Git不一定强制要求但OpenCode在部分功能比如读取仓库信息、应用patch里会用到Git而且你后续大概率也要在一个Git仓库里用它干活所以还是建议装上。检查方式git --version最后是终端本身。macOS用户推荐用iTerm2或者系统自带终端都行Windows用户建议装Windows Terminal别用老的cmdLinux用户随便你用习惯的就行。OpenCode的TUI界面依赖现代终端对Unicode和颜色的支持太老的终端可能显示错乱。2.2 用npm全局安装OpenCode环境没问题后安装就一句话npm install -g opencode-ai装完后验证一下opencode --version如果看到版本号就说明装好了。老版本的包名曾经是opencode后来改成了opencode-ai如果你在别的地方看到npm i -g opencode的旧命令装的可能不是同一个东西注意区分。我建议以现在官方文档为准装opencode-ai这个包。还有一些人喜欢用Homebrew安装macOS上可以试brew install sst/tap/opencode这个方式也可以但我个人更推荐npm因为升级方便一条npm update -g opencode-ai就完事。Homebrew的方式也没毛病看个人习惯。装完之后直接在任意目录敲opencode就能进入TUI界面。第一次启动时它可能会提醒你登录或配置provider先不用急我们下一步就把模型接上。2.3 在VS Code里用上OpenCode插件很多人在热搜里搜“vscode opencode”说明大家都习惯在编辑器里干活。OpenCode官方也提供了VS Code插件搜索opencode就能找到装好后侧边栏会多一个OpenCode面板。这个插件的价值不是替代IDE原生功能而是让你可以在VS Code里直接看到OpenCode的会话、模型列表和任务上下文。你选中一段代码右键选择发送给OpenCode它就会在侧边栏里帮你分析、改错或者写注释改动结果你可以直接预览并一键应用。我的实际感受是写新代码的时候我更喜欢切到终端里用OpenCode的TUI改已有代码、做Code Review的时候VS Code插件更方便因为上下文和文件内容就在眼前。两个形态互补不用纠结哪个更好。如果你用的是JetBrains系IDEOpenCode也有相应插件不过我没有长期使用过这里就不替大家云评测了。VS Code生态相对更成熟一些。2.4 首次启动把界面换成中文顺手调好基础设置OpenCode默认界面是英文的但并不影响功能。网上很多人问怎么设置中文其实OpenCode的界面文本目前没有完整的中文语言包所谓“设置中文”更多是指两件事第一调整语言模型对你的回复语言。你可以在对话里直接说“用中文回答”或者把系统提示词设置成要求中文回复。比如在配置文件里的instructions字段里加上一句“Always reply in Chinese”这样绝大多数模型都会乖乖用中文回复。第二如果你想把TUI的操作说明和菜单提示改成中文目前只能通过改主题/翻译插件实现官方还没有一键语言包。这块我建议别折腾记住几个常用按键就够了/是打开命令面板c新建会话r切换模型e打开上下文文件列表。另外首次启动建议打开设置面板把自动接受编辑、自动执行命令这类权限都先关掉等熟悉了再逐步放开。安全第一别让AI在你没确认前就乱动系统文件。3. 不花一分钱的模型接入三条路线实测3.1 路线一Ollama本地模型彻底零成本还离线可用如果你电脑配置不算太差内存16G以上最好有独立显卡我强烈建议先走本地模型这条路。它最大的优点不是免费而是数据不出本机断网都能用。先安装Ollama。macOS和Windows用户直接去Ollama官网下载对应安装包Linux用户可以用官方安装脚本curl -fsSL https://ollama.com/install.sh | sh装好后拉一个代码能力强的开源模型。目前性价比最高的几个选择代码专用qwen2.5-coder:7b通义千问的代码模型7B量化版体积约4.7GB普通机器跑得还行。全能型llama3.1:8bMeta的开源模型通用对话和代码都凑合但代码能力不如专门的coder模型。轻量代码模型granite3.2:8bIBM的开源模型最近热度很高轻量、代码能力不差还特别强调商用友好。实验党hermes3:8bNous Research的模型创意任务表现不错适合给OpenCode换换口味。拉模型命令ollama pull qwen2.5-coder:7b拉完之后在Ollama还在后台运行的前提下一般安装后会自动作为系统服务运行我们要让OpenCode认识这个本地模型。打开OpenCode的配置文件通常在~/.config/opencode/opencode.json添加类似这样的内容{ $schema: https://opencode.ai/config.json, provider: { ollama: { npm: ai-sdk/ollama, name: Ollama (Local), options: { baseURL: http://localhost:11434/api }, models: { qwen2.5-coder:7b: { name: Qwen2.5 Coder 7B }, granite3.2:8b: { name: Granite 3.2 8B } } } } }不同版本的OpenCode对配置字段的解析会有细微差异如果你打开设置界面看到的是可视化选项直接在里面添加Ollama的baseURL和模型列表也行。配置好之后重新启动OpenCode在模型选择列表里就能看到Ollama下的模型了。选中qwen2.5-coder:7b然后随便让它写点东西试试手。实测下来本地7B模型写小工具脚本、改正则、解释报错是完全够用的但做一个跨文件的大重构会力不从心推理速度也明显比云端大模型慢。我的建议是本地模型接杂活云端免费模型接重活两者互补。这也是我目前最常用的组合。3.2 路线二OpenCode Go套餐官方发的免费额度如果你不想折腾本地模型或者电脑配置确实跑不动那OpenCode官方提供的Go服务就是最省心的免费方案。所谓OpenCode Go是官方提供的模型聚合网关服务。你在OpenCode里执行登录opencode auth login会跳出一个网页让你选择登录方式其中就包括OpenCode Go。登录之后Go套餐会给你分配一些免费额度里面有基础模型和代码模型可以调用。这个免费档对个人日常使用来说很宽松至少我目前一个月的轻中度使用下来没有遇到“额度用完”的情况。Go套餐最大的吸引力在于不用自己配API Key。很多新手死在配置API上又是找Key又是担心扣费Go服务把这些全部省了登录即用。网上有人问“opencode go接入codex”其实只要你登录了Go服务里面可选的模型列表里如果包含了对应模型直接选中就能用不用额外配置。要提醒的是Go免费套餐是官方为了推广生态给的福利最好注册、登录、使用都遵循它的服务条款别拿去做批量任务或者商业爬取以免账号被限制。我自己是拿它作为主力开发模型来用的日常生成代码、改bug完全够。3.3 路线三有免费额度的第三方模型服务第三类免费方案是各家AI开放平台提供的免费额度。这个选择是最丰富的但也要擦亮眼睛。目前市面上有一些平台会提供新用户免费体验额度也有平台会长期提供小幅免费的模型。你只需要去对应平台注册拿到API Key然后在OpenCode的provider配置里填入就可以了。以国内某个硅基流动平台为例它提供了不少开源模型的免费API版本注册后可以在API密钥页面生成一个Key。然后像这样配置到OpenCode的provider里{ provider: { siliconflow: { npm: ai-sdk/openai-compatible, name: SiliconFlow Free, options: { baseURL: https://api.siliconflow.cn/v1, apiKey: 你的Key }, models: { Qwen/Qwen2.5-7B-Instruct: { name: Qwen2.5 7B (Free) } } } } }这里的思路是只要一个服务提供的是OpenAI兼容API你就能用ai-sdk/openai-compatible这个适配器把它接进OpenCode。免费模型型号列表以平台实际为准一般平台文档里会写。这条路的优点是模型质量比本地7B强不少而且是云端跑不占本地资源。缺点是免费额度总有用完的一天而且有些小平台稳定性堪忧可能今天能用明天就关停。我的经验是不要把某个免费API当唯一依赖至少保留本地Ollama这条后路。3.4 切换模型与管理多Provider一次配置随时换脑既然可以接多个模型来源那日常怎么切换就很重要。OpenCode的模型切换很简单在TUI界面按r键会弹出当前可用的模型列表上下选择回车确认就行。如果你有多个provider比如Ollama、SiliconFlow、Go套餐都配着列表里会按provider分组显示。有人问“cc switch连接opencode连接ollama”这是一个常见的场景你是通过cc switch这个工具管理的模型API其实OpenCode这边只要把cc switch提供的本地代理地址当作baseURL来配置即可相当于OpenCode不认识cc switch只认识一个本地OpenAI兼容接口。具体到配置就是provider的baseURL指向http://localhost:8080之类的本地端口然后模型名随便填。这种玩法的好处是你可以把多家的API Key统一托管在cc switch里OpenCode只需要记一个本地地址。但我个人觉得如果模型来源不多直接在OpenCode里配多provider反而更直观。编辑provider的入口在TUI命令面板的/config里或者直接改配置文件。配置文件是JSON格式修改完记得重启OpenCode或者执行配置重载命令新的provider才会生效。我踩过的坑是改了配置没重启以为配置错了白白浪费了一晚上排查时间。4. 让OpenCode真正帮你干活Skills、会话与真实任务4.1 Skills给OpenCode装“技能包”OpenCode 2.0之后最大的亮点之一就是Skills机制。你可以把Skills理解成给AI编码代理装上的专用技能包它让你不用每次都重复描述一堆上下文而是直接喊一句“skill名字”就能调用特定流程。举个例子。官方技能库里有一个类似“代码审查”的skill你只要安装它然后在OpenCode里触发这个skill它就会自动按预置流程检查当前改动的代码输出问题列表和修改建议而不是你每次都要写一段“请帮我审查代码注意安全、性能、可读性”的长指令。安装一个skill的方式很简单opencode skill install skill名称也可以直接在TUI里输入/skill命令浏览和安装。安装完之后在对话中提及技能名OpenCode就会自动加载对应技能的系统提示词和工具调用方式。我的体会是Skill最适合固化那些你做了一次还想再做的任务模板。比如我给自己写了一个“commit message生成”的skill它会自动读git diff、按Conventional Commits规范生成提交信息还写了一个“日志分析”的skill传入日志文件路径就能自动分类报错、统计频率、给出初步定位。这些任务如果没有Skill每次都要重复描述有了Skill之后就变成了一个命令的事。4.2 完整实战让OpenCode写一个批量文件整理脚本光说不练假把式分享一个我实际让OpenCode干过的活批量整理一个乱糟糟的下载文件夹。我当时的下载目录里有几百个文件软件安装包、图片、PDF、压缩包、散落的源码文件夹各种命名混乱。我打开OpenCode选的是本地Qwen模型然后给了它一句话帮我写一个Python脚本扫描~/Downloads目录根据文件扩展名把文件移动到对应的子文件夹图片、视频、文档、压缩包、代码、其他重名文件自动加后缀先dry-run打印要移动的文件确认后再执行。OpenCode很快就生成了一个完整的Python脚本用到pathlib和shutil逻辑基本正确。我在TUI里审查了脚本内容发现它在处理“代码文件夹”识别上不够好——它只按扩展名判断但源码文件夹本身没有扩展名。我在对话里补了一句源码文件夹没有扩展名你检查一下如果路径是文件夹但名字里包含项目的关键词也移到代码文件夹。它立刻改进了逻辑重新生成了带文件夹判断的版本。最后我让它以dry-run模式跑了一遍确认无误后再真正执行。整个过程大概十分钟如果让我手写可能也要半小时。这个例子说明三件事第一OpenCode能把自然语言需求转成可直接运行的脚本第二你得会审它生成的代码至少知道它在干什么第三用dry-run这类安全执行策略能让AI生成的代码在可控范围内执行。别让AI直接改你系统里的文件先跑一遍模拟确认逻辑没问题再真刀真枪上。4.3 会话管理归档的对话到底去哪了用OpenCode时间长了你会积累很多会话记录有些是当时有用但暂时不想看到的。TUI里可以执行归档操作把会话收起来。很多人就好奇归档的对话到哪了OpenCode的会话记录默认存储在用户数据目录下在macOS和Linux上是~/.local/share/opencode/Windows上一般在%USERPROFILE%\.local\share\opencode\。里面有按会话ID组织的JSON文件记录了对话消息、使用的模型、包含的上下文文件等。归档操作本质上是把这些会话打上“归档”标记它们在TUI的默认列表里不再显示但数据文件并没有删除。你可以在配置里打开“显示归档会话”之类的选项把它们重新列出来也可以直接去存储目录找到对应的JSON文件。我建议养成一个习惯重要的会话手动导出或备份。因为OpenCode目前还没有特别强大的云同步如果你重装系统或者清理用户目录这些会话数据就没了。虽然大部分对话记录没有长期价值但有几次我为了回顾一个重构方案的完整讨论过程翻遍了存储目录才恢复出历史记录血泪教训。5. 免费方案踩坑实录与排查手册5.1 invalid api key90%是配置问题“opencode invalid api key”这个报错是新手区最常见的拦路虎。我帮人排查过不少次大部分情况是Key配错了而不是模型服务挂了。首先检查Key本身确认复制的时候没有多复制空格没有少复制前缀。有些平台的Key是非明文生成的你只在创建时能看到一次忘了就得重新建一个。其次是检查配置文件的路径和字段。OpenCode对不同provider的字段名要求不一样有的用apiKey有的用api_key一旦填错位置就显示invalid。最省心的方法是直接在配置文件里搜索你填Key的那一行确认它是否在正确的provider节点下面。我有一次把Key填到了模型名称的字段里硬是报了半小时invalid api key。最后确认一下你配的Key是否真的对应该服务商。不同平台的Key不能混用OpenAI的Key填到某个兼容网关服务里除非它明确支持否则照样报错。如果以上都排除了那就是服务商侧的问题可能是Key过期、欠费或者临时故障。去对应的平台控制台查一眼Key状态大部分问题都一目了然。5.2 模型选择器里一个模型也没有热词里有人问“opencode desktop选择模型那里一个模型也没有了”我推测他说的是TUI界面里的模型列表突然变空。这个问题我遇到过两次原因各不相同。第一次是因为配置文件写坏了某个provider的models节点写成了空对象{}导致整个provider不被加载。排查方法是打开配置文件用JSON校验工具检查格式看models节点下面有没有实际的模型条目。第二次是连接本地Ollama时Ollama服务没起来。OpenCode能接受provider配置但实际加载模型列表时要调Ollama的API如果localhost:11434连不上模型列表就会空。解决办法是先执行ollama list确认服务通不通再看OpenCode日志。另外有一种情况是版本升级后旧配置文件里的schema不再兼容。这时候OpenCode会静默忽略掉部分配置模型列表就会异常。建议升级后及时查看配置文件的schema提示或者直接备份旧配置重写一份。5.3 提示连不上Ollama / 找不到模型这个问题的典型表现是你选了Ollama的模型但发消息后一直转圈最后报错说连接不上。第一步检查Ollama进程是否在跑。macOS上可以看菜单栏有没有Ollama图标Linux上执行curl http://localhost:11434如果返回类似Ollama is running的信息进程正常。如果拒绝连接先执行ollama serve手动启动服务。第二步检查模型名是否准确。OpenCode配置里的模型名必须和ollama list输出的名字完全一致包括标签部分比如qwen2.5-coder:7b和qwen2.5-coder是不一样的。你配置成后者Ollama找不到精确匹配就会报错。第三步检查baseURL是否多写了路径。Ollama的API根路径是http://localhost:11434如果按OpenAI的惯例写成http://localhost:11434/v1部分版本会出问题。OpenCode官方适配器会自己拼接路径所以baseURL一般只填根地址。5.4 常见问题速查表现象大概率原因处理方案invalid api keyKey配置错/过期重新复制Key检查JSON字段位置去平台确认状态模型列表为空provider配置损坏或Ollama未运行校验JSON确认Ollama服务检查schema兼容性连不上OllamaOllama服务没启动或端口被占ollama list测试必要时ollama serve或换端口会话无法归档后找回归档只是标记文件仍在本地目录去~/.local/share/opencode/找历史JSON提示文件写入被拒绝权限配置太严格或目录只读检查工作目录权限或手动在终端里执行命令TUI按键失灵终端不兼容或快捷键冲突换Windows Terminal/iTerm2检查终端插件映射升级后配置丢失版本升级导致schema不兼容备份旧配置按新schema重写别覆盖安装一个会话中切换模型后“失忆”部分模型不支持跨模型上下文继承切换模型后重新描述需求或开新会话5.5 想省钱的三个隐藏技巧最后分享几个我在“免费省钱”路线上攒下的实用技巧。第一个技巧是给不同难度的任务分配不同模型。简单的脚本、格式转换、正则表达式这种活直接用本地Ollama的7B模型再便宜不过中大型重构、棘手bug才切到云端免费额度的强模型。这样既能保证效率又不会让一次简单对话浪费掉宝贵的免费额度。第二个技巧是善用maxTokens限制。在OpenCode的模型配置里可以给单个模型设置请求的最大输出token数。不是所有任务都需要生成几百行代码把一些小任务的maxTokens调低能减少云端资源消耗。对按token计费的免费额度来说积少成多能撑很久。第三个技巧是本地模型跑“草稿”云端模型做“定稿”。我经常先让本地Qwen快速生成一个初版然后拷给云端强模型审查改进。这样做质量的下降不明显但成本比直接让云端从头写低得多。说白了就是让便宜的先干活贵的只做把关。最后再分享一个我自己的小习惯用了OpenCode这段时间我最大的感受是省钱的本质不是找到一个永久免费的替代品而是建立一个“按需分配模型”的意识。把简单活交给轻量或本地模型把复杂活交给云端强模型关键活才值得花一点token费用。这种灵活调配的能力恰恰是OpenCode这类可自选模型工具给我的最大自由度。最后建议新上手的朋友别一上来就追求复杂场景先用它干一件最简单的任务比如写个小脚本、整理一份文件、解释一段报错日志。跑通一次从“输入需求”到“得到结果”的完整流程你自然就明白它适合干什么、不适合干什么了。等熟悉之后再慢慢研究Skills、多Provider组合和自动化工作流。免费的东西不一定最强大但它给了你空间去学习、去掌控、去玩出适合自己的一套玩法。这套玩法是那些贵价订阅给不了你的。
