最近我把主力 AI 编码助手从网页端迁到了终端里的 OpenCode用下来最直观的感受是它把AI 对话改代码这件事拉回到了开发者最熟悉的编辑器/终端环境里不需要来回复制粘贴模型也接得干净利落。这篇就围绕 OpenCode 安装、模型配置、Skill 扩展、局域网 serve、常见报错这几个高频问题把我在实际部署和使用中踩过的坑、验证过的方案一次性讲清楚。如果你准备在 Linux/macOS/Windows 上用开源 CLI 工具接入 Codex、Ollama、Granite 这类模型或者想让局域网内的其他设备也能调起 OpenCode 的能力这篇应该能帮你省掉不少查文档的功夫。1. 先搞清楚 OpenCode 是什么它的定位和优势在哪里很多人第一次听到 OpenCode会下意识把它和 Cursor、Continue 这类 IDE 插件混为一谈。其实它的核心形态是一个跑在终端里的 AI 编码代理你可以在任意项目目录下启动它通过自然语言让 AI 读取代码、修改文件、执行命令甚至是批量重构。它更接近 Claude Code 或者 Codex CLI 这类工具而不是一个能聊天的编辑器插件。1.1 终端 AI 助手和 IDE 插件到底有什么区别IDE 插件的思路是在编辑器里给你一个对话窗口AI 拿到了你的选区、当前文件、诊断信息之后给建议你需要手动接受 diff。OpenCode 的思路是在终端里给你一个完整的 AI 代理它自己就能操作文件系统、运行测试、查看 git diff你只需要告诉它目标它会自己规划步骤并执行。举个例子我经常让它做这样的事把这个项目的错误处理统一改成自定义异常然后跑一遍测试告诉我哪里挂了。在IDE插件里你需要手动指定文件、手动应用补丁在 OpenCode 里它自己会搜索相关代码、修改文件、执行测试命令然后回报结果。这种差异在重构老项目时尤其明显。1.2 为什么我最终选择了 OpenCode选型时我对比过几款工具最终留下 OpenCode 有四个原因。第一开源且本地优先。配置文件和会话记录都是本地文件代码仓库默认不会上传到某个私有的云服务。对在意代码合规和隐私的团队来说这一点能省去不少流程上的麻烦。第二模型接入是真的灵活。它内置支持多种 provider既能连 OpenAI 的 Codex、也能连 Ollama 上的本地模型还有 IBM Granite 这类开发者模型。你可以一条命令切换不用在不同工具之间来回跳。第三操作效率确实高。它在终端里提供了一套快捷交互用引用文件、用#引入终端输出、用/model切换模型、用/sessions恢复历史会话。用习惯了之后整个工作流可以完全不离开终端。第四有独立的桌面版和编辑器扩展。不在终端工作的人也能用Visual Studio Code 扩展和 JetBrains 插件都有PyCharm、IDEA 用户同样能接上。2. 安装 OpenCode从命令行到桌面端一次性搞定OpenCode 的安装方式很多macOS、Linux、Windows 都有对应渠道。我建议按用途来选择安装方式主要用终端的走包管理器想要图形界面的直接装桌面版需要在 IDE 里用的就装对应插件。2.1 macOS、Linux、Windows 三种安装方式对比macOS 上最省事的方式是 Homebrewbrew install opencode装完之后在任意项目目录里输入opencode就能启动。这条命令会安装最新稳定版后续升级用brew upgrade opencode就行。Linux 上官方推荐用安装脚本curl -fsSL https://opencode.ai/install | bash脚本会检测系统架构下载对应的二进制文件到~/.opencode/bin并在 shell 配置里追加 PATH。执行完后重开终端运行opencode --version能看到版本号就说明没问题。Windows 上可以用 Scoopscoop install opencode也可以直接从 GitHub Releases 页面下载 exe 文件解压后把路径加入系统 PATH。我个人更推荐 Scoop因为后续scoop update opencode一行命令就能升级。如果你不想用包管理器官方也提供了 npm 安装方式npm install -g opencode-ai我实测下来 npm 包和二进制版本功能一致适合已经把 Node.js 环境作为标配的开发者。2.2 安装后的初始化配置第一次运行opencode时它会询问你使用哪个模型服务商。这里先不用急着选因为后面随时可以改。你只需要确认一件事你的 API 密钥从哪里来。如果你用的是 opencode 官方提供的 Go 订阅计划可以直接在交互界面选择opencode作为 provider然后回车进入登录流程。如果你有自己的 Codex、OpenAI 或者其他模型 API 密钥选择对应的 provider把密钥填进去即可。密钥保存位置一般在~/.local/share/opencode/auth.jsonLinux/macOS或者%APPDATA%\opencode\auth.jsonWindows手动编辑这个文件也可以更新密钥。注意配置完成后建议立刻运行一次opencode发一句你好确认模型能正常响应。如果这一步就报错后面所有的功能都会受影响。常见原因基本集中在 provider 选择错误、密钥填错、网络不通这几类。2.3 桌面版、VS Code 插件和 JetBrains 插件不想整日泡在终端里的朋友可以直接装 OpenCode 桌面版。桌面版内置了编辑器界面左侧是文件树右侧是会话面板用起来很像一个轻量级 AI IDE。下载地址在官网首页就能找到Windows 和 macOS 都有对应的安装包。VS Code 用户直接在扩展市场搜索opencode找到官方扩展安装即可。如果搜不到大概率是扩展市场来源设置的问题——VS Code 默认会从 Microsoft Marketplace 拉取扩展你可以检查一下是否被切换到了 Open VSX 或者其他来源。JetBrains 系IDEA、PyCharm、GoLand 等则是在插件市场搜索opencode安装后会在右侧工具窗口出现一个 OpenCode 面板可以直接在 IDE 里对话、引用项目文件。这个插件对于习惯 JetBrains 重构功能的老用户来说很顺手AI 改动代码后可以直接使用 IDE 的 diff 视图审阅。提示如果你在使用 Cursor也尝试搜过 OpenCode 扩展但找不到这是正常的。Cursor 有自己的一套扩展体系去它的扩展市场搜不到 OpenCode 是预期行为直接用 OpenCode 官方桌面版或者独立 VS Code 就行。3. OpenCode 核心使用姿势模型切换、会话管理与 Skill 扩展安装只是开始真正影响效率的是日常操作方式和扩展机制。这一节讲几个高频动作怎么切换到合适的模型、怎么管理历史会话、怎么通过 Skill 让 OpenCode 具备自定义能力。3.1 进入第一个会话引用文件、引入终端输出在项目根目录启动opencode后你会进入一个交互式 TUI 界面。最下面一行是输入框你可以直接输入自然语言指令。这里有几个非常重要的快捷键和语法。使用符号可以引用具体文件。比如我输入看看src/main.py里的逻辑帮我优化一下它会精准读取该文件作为上下文。这个用法在改动大型项目的局部模块时特别好用不用把整个仓库都塞给模型既省 token 又减少干扰。使用#符号可以引入终端输出。比如你刚跑完一条命令报错了直接在输入框里输入#加上错误信息它会自动把最近一次终端输出作为上下文。这样你描述问题的时候就不用再手动复制大段报错文本了。如果你临时改主意想换模型输入/model会弹出模型列表上下键选择、回车确认。整个切换过程是热切换不需要重启会话当前上下文会保留。这个我实测在对比模型效果时非常方便同一个任务在 Codex 和 Granite 之间来回切很快就知道哪个更适合手头的代码风格。3.2 历史会话存在哪怎么找回归档的对话用过一段时间后你会积累很多历史会话。如果你找不到之前的对话在哪儿先别急着开新会话。在 OpenCode TUI 里输入/sessions会列出所有历史会话记录按时间排序选中任意一条就能恢复上下文继续对话。底层存储位置也有规律Linux/macOS 在~/.local/share/opencode/目录下Windows 在%APPDATA%\opencode\目录下。里面会有 sessions 目录每个会话一个 JSON 文件包含消息记录、文件改动记录、时间戳等信息。如果你需要备份或者迁移直接把整个目录拷走就行。注意目录里通常还有 storage 目录用于存放消息附件和其他临时文件。我建议定期备份 sessions 目录就够了storage 目录比较占空间不需要全量打包。3.3 Skill 怎么安装、怎么自己写一个Skill 是 OpenCode 很能打的一个扩展机制它允许你通过自定义指令集让 AI 掌握特定的工作流程。比如你可以写一个提交信息生成 Skill让 AI 按照你团队的规范生成 git commit message也可以写一个代码审阅 Skill让它每次都按照固定维度检查代码。Skill 的存放位置是项目内的.opencode/skills/目录。每个 Skill 就是一个子目录里面包含一个SKILL.md文件。这个文件的格式不复杂示例--- name: git-commit description: 根据 git diff 生成符合团队规范的提交信息 --- 当用户要求生成提交信息时执行以下步骤 1. 运行 git diff 查看变更 2. 识别变更类型feat、fix、refactor、docs、test 3. 输出规范格式type(scope): subject保存后回到 OpenCode 会话中输入生成提交信息它就能根据这个 Skill 的指示来处理。Skill 里还可以包含脚本文件OpenCode 会调用脚本完成更复杂的自动化操作。我还尝试过从社区下载别人写好的 Skill 放到对应目录效果立竿见影。GitHub 上已经有不少现成 Skill 仓库比如 oh-my-opencode 这类聚合项目下载后解压到.opencode/skills/即可。提示写 Skill 时有一个容易踩的坑——description 字段要尽量描述什么场景下触发而不是它能做什么。OpenCode 是根据语义匹配来调用 Skill 的description 写得越贴近用户的自然语言触发准确率越高。3.4 配置 opencode 2.0 版本的新特性如果你用的是 OpenCode 2.0 之后的版本配置文件的组织方式和旧版有些不同。新版主配置集中在opencode.json支持按项目覆盖。比如你可以在项目根目录放一个opencode.json覆盖全局配置里的模型参数、Skill 启用列表、环境变量等。一个典型的配置文件长这样{ $schema: https://opencode.ai/config.json, model: gpt-5, provider: { ollama: { models: [ { name: granite3-dense:8b, baseURL: http://localhost:11434/v1 } ] } } }这个配置的意思是默认模型用 gpt-5同时自定义了一个名为 ollama 的 provider里面接入本地的 granite3-dense:8b 模型。配置完成后在 TUI 里用/model切换就能看到这个本地模型。新版对 provider 的配置灵活度很高这也是它能同时接云端模型和本地模型的根本原因。4. 模型接入进阶Go 订阅、Codex、Ollama 与 Granite 的完整接法OpenCode 真正让人舒服的地方在于模型接入的灵活性。你既可以用官方订阅的托管通道也可以带上自己的密钥接入 Codex还可以在完全离线的环境里接 Ollama 上的本地模型。这一节我把自己试过的几种接法按场景拆开讲。4.1 opencode go 订阅计划怎么用如果你不想分别购买多个模型厂商的 API直接用 opencode 官方的 Go 订阅计划会比较省心。它相当于一个聚合通道订阅之后你不需要关心底层具体走了哪个模型的计费只管在 OpenCode 里切换模型就行。使用方式分两种。第一种是纯登录方式在 OpenCode 的 provider 里选择 opencode然后根据提示在浏览器里授权登录。第二种是密钥方式在 opencode 官网的账户后台生成 API 密钥然后把密钥填入 auth.json 或者环境变量OPENCODE_API_KEY中。两种方式我都试过稳定性和速度没有明显差别看你习惯哪种。对于已经买了订阅但不知道怎么连接的用户我建议先检查密钥是否写对了位置。在终端里运行echo $OPENCODE_API_KEY如果输出为空说明没有设置环境变量。用登录方式的话直接重新在 TUI 里选 provider 走一遍授权流程一般两分钟内能解决。另外Go 订阅计划里可以接入 Codex 模型选模型时注意不要选成旧版 Codex 的 experimental 通道选“codex”类目下的正式模型更稳定。这个细节在社区里经常被问我一开始也踩过切换到正式通道后就再没报错过。4.2 局域网访问opencode serve 的正确用法OpenCode 的 HTTP 服务模式非常适合局域网内共享能力。比如你有一台办公用的 Linux 服务器配置了模型通道其他同事的电脑可以通过局域网访问这台服务器上的 OpenCode 接口不用每台机器都配密钥。启动局域网服务的方式是opencode serve --hostname 0.0.0.0 --port 4096默认情况下opencode serve只监听 127.0.0.1也就是只能本机访问。要支持局域网访问必须指定--hostname 0.0.0.0。启动后其他设备可以通过http://你的IP:4096访问接口在浏览器里能看到一个简单的前端页面也可以用支持自定义 provider 的客户端比如 CC Switch指向这个地址。如果你希望服务在后台常驻我习惯用 systemd 或者 pm2 托管。以下是一个 systemd 服务文件示例[Unit] DescriptionOpenCode HTTP Server Afternetwork.target [Service] ExecStart/usr/local/bin/opencode serve --hostname 0.0.0.0 --port 4096 Restartalways User你的用户名 [Install] WantedBymulti-user.target注意把服务暴露到局域网意味着同一网段的其他机器都能访问。如果你的网络环境里有不信任的设备建议在服务前面加一层简单的访问令牌校验不要让端口裸奔。4.3 用 CC Switch 连接 opencode 再连接 ollamaCC Switch 是一个模型切换工具很多人喜欢把它和 OpenCode 串起来用做成本地模型统一入口。实际链路是CC Switch 作为客户端将请求转发给opencode serve暴露的接口再由 OpenCode 路由到 Ollama 上的本地模型。这样的好处是你的前端工具只需要配一个自定义 provider后端模型想换就换。具体配置分两步。第一步在 OpenCode 的配置里添加 Ollama provider确保 Ollama 的模型能通过 OpenCode 正常调用。第二步在 CC Switch 里新增一个自定义 Provider地址填http://OpenCode所在机器的IP:4096协议类型选 OpenAI 兼容格式模型名填你在 OpenCode 里配置好的模型名。保存后在 CC Switch 里选中这个 Provider就能把请求打到 OpenCode最终落到 Ollama 的本地模型上。这一步我踩过比较多的问题是连上了但模型一直报 404。排查思路是先确认 OpenCode 侧能不能正常调用 Ollama 模型opencode run hi --model ollama/granite3-dense:8b如果这条命令能正常返回说明 OpenCode 到 Ollama 的链路是通的。此时再去 CC Switch 里检查模型名是否和 OpenCode 配置里的模型名完全一致。注意CC Switch 侧填的模型名不是 Ollama 里的原始模型名而是 OpenCode 的 provider 配置中定义的模型 name很多人在这里写错。4.4 完全本地化OpenCode 接 Ollama 和 Granite如果你对数据隐私比较敏感或者有些代码根本不适合发给云端模型那就要走完全本地化的路线。OpenCode 接 Ollama 是目前最成熟的本地方案。以 IBM Granite 为例Granite 是 IBM 开源的代码生成模型在 Ollama 上可以直接拉取ollama pull granite3-dense:8b拉取完成后在 OpenCode 的opencode.json中配置 Ollama provider{ provider: { ollama: { baseURL: http://localhost:11434/v1, models: [ { name: granite3-dense:8b, aliases: [granite] } ] } } }配置完成后启动 OpenCode 并切换到ollama/granite3-dense:8b模型就能在没有外网的情况下完成代码生成、解释、重构等任务。本地模型的速度完全取决于你的机器算力。我实测 8B 模型在 32GB 内存的 M 系列芯片上响应很流畅日常改 bug 完全够用如果做大规模重构建议上更大的模型。提示本地模型和云端模型在使用体验上的差距主要在指令遵循和复杂逻辑推理上。简单任务生成单函数、解释代码、写测试用例本地 8B 模型表现很好跨多文件的深层重构仍然是云端大模型更稳。我的习惯是日常简单操作走本地大型重构走云端两个通道在 OpenCode 里切换模型也就几秒钟的事。5. 高频报错排查从 free tier 报错到模型列表为空使用过程中难免会遇到一些报错尤其在你尝试把 OpenCode 接入到其他工具、或者配置自己的 provider 时。下面几个问题是社区热搜里出现频率最高的我把原因和解决思路整理出来。5.1 error from provider (console): opencodes free tier can only be used from within opencode这个报错是很多人在用 CC Switch 或其他自定义客户端连接 OpenCode 时遇到的。报错的字面意思是opencode 的免费额度只能在 OpenCode 客户端内部使用。也就是说当你使用opencode serve或某种外部通道去调用 opencode 自带的免费模型时服务端会拒绝请求因为免费通道只允许在官方客户端内使用。出现这个报错后先不要慌。你需要确认自己是不是在用 opencode 官方免费模型作为 provider。如果你是通过外部工具比如 CC Switch调用 opencode serve 的接口而 OpenCode 内部使用的又是 opencode 的免费通道那这个报错是预期行为官方就是不允许这样转发使用。解决办法有两个方向一是换用你自己的 API 密钥接入其他 provider比如 OpenAI、Codex然后通过 serve 共享二是订阅 opencode 的 Go 计划用付费通道替代免费通道。付费通道不受这个限制可以正常被外部客户端调用。注意如果只是本地使用 OpenCode TUI 或桌面版几乎不会遇到这个报错。一旦你开始做局域网共享或者让其他工具来调 OpenCode 的接口就必须检查模型通道的性质。5.2 桌面版选择模型那里一个模型也没有了有用户反馈说打开 OpenCode 桌面版选择模型的下拉列表是空的。根据我排查的经验大概率是以下三类原因之一。第一配置文件被写坏了。桌面版会读取全局的opencode.json如果 JSON 格式错误或者 provider 配置缺失模型列表就加载不出来。排查方式是打开终端在任意目录下运行opencode看看 TUI 里能不能正常列出模型。如果 TUI 也是空的问题几乎可以确定在配置上。第二认证失效。如果你使用的是需要登录授权的 provider比如 opencode 官方通道token 过期之后模型列表会加载失败。桌面版侧重新登录一次即可或者在 auth.json 里更新密钥。第三Go 订阅计划到期或没有绑定密钥。Go 计划欠费/到期之后桌面端会呈现模型列表空的现象但在终端里往往会有更明确的报错信息。建议先跑一遍终端版把具体报错记下来再回桌面版处理。5.3 模型切换时提示 provider 未配置在 TUI 里输入/model切换模型时偶尔会遇到某个模型无法选择、提示 provider 未配置的情况。这通常是因为模型对应的 provider baseURL 没有写全。例如你只配置了模型名却没有配置 baseURLOpenCode 就不知道要把请求发到哪里。解决办法是打开opencode.json检查每个 provider 是否都有完整的baseURL和模型列表。特别是自定义本地模型时baseURL一定要写对Ollama 的默认地址是http://localhost:11434/v1如果你改了端口这里也要同步改。另一个容易忽略的是模型别名如果你在配置里加了aliases在 TUI 里切换时要使用别名而不是原始模型名。我不止一次在切换本地模型时发现找不到模型最后检查都是 aliases 和实际输入不一致。5.4 局域网客户端连接超时、页面打不开局域网访问opencode serve时常见的症状是本机能访问别的电脑访问不了。优先检查两个地方。一是监听地址是否真的绑到了0.0.0.0很多人在启动时漏了这个参数服务只对本机开放。二是有没有防火墙拦截 4096 端口Linux 上尤其常见。sudo ufw allow 4096/tcp如果开启了防火墙先放行对应端口再试。另外一点跨设备访问时建议直接用 IP 地址而不是主机名因为有些内网环境下主机名解析不稳定。我之前在办公网里就遇到过每次都解析超时的情况换成 IP 后立刻正常。5.5 常见问题速查表问题现象常见原因解决思路终端版正常桌面版模型列表为空桌面版配置与全局配置不一致在桌面版重新选择 provider或手动修复全局 opencode.json外部工具调用 opencode serve 报 free tier 错误使用免费通道做外部转发换用自己的 API 密钥或订阅 Go 付费通道CC Switch 连接 OpenCode 模型返回 404模型名与配置不一致在 OpenCode 配置中使用定义的模型 name而非原始模型名局域网其他设备无法访问 serve 端口监听地址或防火墙问题使用--hostname 0.0.0.0放行对应端口切换模型时找不到本地模型provider 未配置或别名错误补齐 baseURL确认别名正确历史会话找不到存储目录变更或误删查看~/.local/share/opencode/sessions用/sessions恢复安装后命令不存在PATH 未生效重开终端或手动把安装目录加入 PATH6. 我的一些个人经验和最后想说的实际操作中我发现OpenCode 这类终端 AI 代理工具真正提升效率的不是它支持多少个模型而是会话可恢复、文件可引用、Skill 可扩展、服务可共享这套完整的工作流。我现在每天的工作模式已经固定下来日常小改动用本地 Granite 模型快速跑一遍遇到大重构切换到 Codex 或云端模型通过/sessions随时恢复昨天没聊完的上下文。这个过程完全在终端里完成不打断编码节奏。最后分享一个小技巧在配置 Skill 的时候不要贪多先按自己团队最痛的一两个流程写起。比如我们最先写的commit 信息生成生效后紧接着写了代码审阅。每跑通一个 SkillOpenCode 的可用性就上一个台阶。相对于不停地研究新功能把已有的几个高频能力打磨稳定实际收益更大。这个经验是从我自己踩坑中得来的希望对你有用。 OpenCode实战指南：终端AI编码助手的安装配置与模型接入
最近我把主力 AI 编码助手从网页端迁到了终端里的 OpenCode用下来最直观的感受是它把AI 对话改代码这件事拉回到了开发者最熟悉的编辑器/终端环境里不需要来回复制粘贴模型也接得干净利落。这篇就围绕 OpenCode 安装、模型配置、Skill 扩展、局域网 serve、常见报错这几个高频问题把我在实际部署和使用中踩过的坑、验证过的方案一次性讲清楚。如果你准备在 Linux/macOS/Windows 上用开源 CLI 工具接入 Codex、Ollama、Granite 这类模型或者想让局域网内的其他设备也能调起 OpenCode 的能力这篇应该能帮你省掉不少查文档的功夫。1. 先搞清楚 OpenCode 是什么它的定位和优势在哪里很多人第一次听到 OpenCode会下意识把它和 Cursor、Continue 这类 IDE 插件混为一谈。其实它的核心形态是一个跑在终端里的 AI 编码代理你可以在任意项目目录下启动它通过自然语言让 AI 读取代码、修改文件、执行命令甚至是批量重构。它更接近 Claude Code 或者 Codex CLI 这类工具而不是一个能聊天的编辑器插件。1.1 终端 AI 助手和 IDE 插件到底有什么区别IDE 插件的思路是在编辑器里给你一个对话窗口AI 拿到了你的选区、当前文件、诊断信息之后给建议你需要手动接受 diff。OpenCode 的思路是在终端里给你一个完整的 AI 代理它自己就能操作文件系统、运行测试、查看 git diff你只需要告诉它目标它会自己规划步骤并执行。举个例子我经常让它做这样的事把这个项目的错误处理统一改成自定义异常然后跑一遍测试告诉我哪里挂了。在IDE插件里你需要手动指定文件、手动应用补丁在 OpenCode 里它自己会搜索相关代码、修改文件、执行测试命令然后回报结果。这种差异在重构老项目时尤其明显。1.2 为什么我最终选择了 OpenCode选型时我对比过几款工具最终留下 OpenCode 有四个原因。第一开源且本地优先。配置文件和会话记录都是本地文件代码仓库默认不会上传到某个私有的云服务。对在意代码合规和隐私的团队来说这一点能省去不少流程上的麻烦。第二模型接入是真的灵活。它内置支持多种 provider既能连 OpenAI 的 Codex、也能连 Ollama 上的本地模型还有 IBM Granite 这类开发者模型。你可以一条命令切换不用在不同工具之间来回跳。第三操作效率确实高。它在终端里提供了一套快捷交互用引用文件、用#引入终端输出、用/model切换模型、用/sessions恢复历史会话。用习惯了之后整个工作流可以完全不离开终端。第四有独立的桌面版和编辑器扩展。不在终端工作的人也能用Visual Studio Code 扩展和 JetBrains 插件都有PyCharm、IDEA 用户同样能接上。2. 安装 OpenCode从命令行到桌面端一次性搞定OpenCode 的安装方式很多macOS、Linux、Windows 都有对应渠道。我建议按用途来选择安装方式主要用终端的走包管理器想要图形界面的直接装桌面版需要在 IDE 里用的就装对应插件。2.1 macOS、Linux、Windows 三种安装方式对比macOS 上最省事的方式是 Homebrewbrew install opencode装完之后在任意项目目录里输入opencode就能启动。这条命令会安装最新稳定版后续升级用brew upgrade opencode就行。Linux 上官方推荐用安装脚本curl -fsSL https://opencode.ai/install | bash脚本会检测系统架构下载对应的二进制文件到~/.opencode/bin并在 shell 配置里追加 PATH。执行完后重开终端运行opencode --version能看到版本号就说明没问题。Windows 上可以用 Scoopscoop install opencode也可以直接从 GitHub Releases 页面下载 exe 文件解压后把路径加入系统 PATH。我个人更推荐 Scoop因为后续scoop update opencode一行命令就能升级。如果你不想用包管理器官方也提供了 npm 安装方式npm install -g opencode-ai我实测下来 npm 包和二进制版本功能一致适合已经把 Node.js 环境作为标配的开发者。2.2 安装后的初始化配置第一次运行opencode时它会询问你使用哪个模型服务商。这里先不用急着选因为后面随时可以改。你只需要确认一件事你的 API 密钥从哪里来。如果你用的是 opencode 官方提供的 Go 订阅计划可以直接在交互界面选择opencode作为 provider然后回车进入登录流程。如果你有自己的 Codex、OpenAI 或者其他模型 API 密钥选择对应的 provider把密钥填进去即可。密钥保存位置一般在~/.local/share/opencode/auth.jsonLinux/macOS或者%APPDATA%\opencode\auth.jsonWindows手动编辑这个文件也可以更新密钥。注意配置完成后建议立刻运行一次opencode发一句你好确认模型能正常响应。如果这一步就报错后面所有的功能都会受影响。常见原因基本集中在 provider 选择错误、密钥填错、网络不通这几类。2.3 桌面版、VS Code 插件和 JetBrains 插件不想整日泡在终端里的朋友可以直接装 OpenCode 桌面版。桌面版内置了编辑器界面左侧是文件树右侧是会话面板用起来很像一个轻量级 AI IDE。下载地址在官网首页就能找到Windows 和 macOS 都有对应的安装包。VS Code 用户直接在扩展市场搜索opencode找到官方扩展安装即可。如果搜不到大概率是扩展市场来源设置的问题——VS Code 默认会从 Microsoft Marketplace 拉取扩展你可以检查一下是否被切换到了 Open VSX 或者其他来源。JetBrains 系IDEA、PyCharm、GoLand 等则是在插件市场搜索opencode安装后会在右侧工具窗口出现一个 OpenCode 面板可以直接在 IDE 里对话、引用项目文件。这个插件对于习惯 JetBrains 重构功能的老用户来说很顺手AI 改动代码后可以直接使用 IDE 的 diff 视图审阅。提示如果你在使用 Cursor也尝试搜过 OpenCode 扩展但找不到这是正常的。Cursor 有自己的一套扩展体系去它的扩展市场搜不到 OpenCode 是预期行为直接用 OpenCode 官方桌面版或者独立 VS Code 就行。3. OpenCode 核心使用姿势模型切换、会话管理与 Skill 扩展安装只是开始真正影响效率的是日常操作方式和扩展机制。这一节讲几个高频动作怎么切换到合适的模型、怎么管理历史会话、怎么通过 Skill 让 OpenCode 具备自定义能力。3.1 进入第一个会话引用文件、引入终端输出在项目根目录启动opencode后你会进入一个交互式 TUI 界面。最下面一行是输入框你可以直接输入自然语言指令。这里有几个非常重要的快捷键和语法。使用符号可以引用具体文件。比如我输入看看src/main.py里的逻辑帮我优化一下它会精准读取该文件作为上下文。这个用法在改动大型项目的局部模块时特别好用不用把整个仓库都塞给模型既省 token 又减少干扰。使用#符号可以引入终端输出。比如你刚跑完一条命令报错了直接在输入框里输入#加上错误信息它会自动把最近一次终端输出作为上下文。这样你描述问题的时候就不用再手动复制大段报错文本了。如果你临时改主意想换模型输入/model会弹出模型列表上下键选择、回车确认。整个切换过程是热切换不需要重启会话当前上下文会保留。这个我实测在对比模型效果时非常方便同一个任务在 Codex 和 Granite 之间来回切很快就知道哪个更适合手头的代码风格。3.2 历史会话存在哪怎么找回归档的对话用过一段时间后你会积累很多历史会话。如果你找不到之前的对话在哪儿先别急着开新会话。在 OpenCode TUI 里输入/sessions会列出所有历史会话记录按时间排序选中任意一条就能恢复上下文继续对话。底层存储位置也有规律Linux/macOS 在~/.local/share/opencode/目录下Windows 在%APPDATA%\opencode\目录下。里面会有 sessions 目录每个会话一个 JSON 文件包含消息记录、文件改动记录、时间戳等信息。如果你需要备份或者迁移直接把整个目录拷走就行。注意目录里通常还有 storage 目录用于存放消息附件和其他临时文件。我建议定期备份 sessions 目录就够了storage 目录比较占空间不需要全量打包。3.3 Skill 怎么安装、怎么自己写一个Skill 是 OpenCode 很能打的一个扩展机制它允许你通过自定义指令集让 AI 掌握特定的工作流程。比如你可以写一个提交信息生成 Skill让 AI 按照你团队的规范生成 git commit message也可以写一个代码审阅 Skill让它每次都按照固定维度检查代码。Skill 的存放位置是项目内的.opencode/skills/目录。每个 Skill 就是一个子目录里面包含一个SKILL.md文件。这个文件的格式不复杂示例--- name: git-commit description: 根据 git diff 生成符合团队规范的提交信息 --- 当用户要求生成提交信息时执行以下步骤 1. 运行 git diff 查看变更 2. 识别变更类型feat、fix、refactor、docs、test 3. 输出规范格式type(scope): subject保存后回到 OpenCode 会话中输入生成提交信息它就能根据这个 Skill 的指示来处理。Skill 里还可以包含脚本文件OpenCode 会调用脚本完成更复杂的自动化操作。我还尝试过从社区下载别人写好的 Skill 放到对应目录效果立竿见影。GitHub 上已经有不少现成 Skill 仓库比如 oh-my-opencode 这类聚合项目下载后解压到.opencode/skills/即可。提示写 Skill 时有一个容易踩的坑——description 字段要尽量描述什么场景下触发而不是它能做什么。OpenCode 是根据语义匹配来调用 Skill 的description 写得越贴近用户的自然语言触发准确率越高。3.4 配置 opencode 2.0 版本的新特性如果你用的是 OpenCode 2.0 之后的版本配置文件的组织方式和旧版有些不同。新版主配置集中在opencode.json支持按项目覆盖。比如你可以在项目根目录放一个opencode.json覆盖全局配置里的模型参数、Skill 启用列表、环境变量等。一个典型的配置文件长这样{ $schema: https://opencode.ai/config.json, model: gpt-5, provider: { ollama: { models: [ { name: granite3-dense:8b, baseURL: http://localhost:11434/v1 } ] } } }这个配置的意思是默认模型用 gpt-5同时自定义了一个名为 ollama 的 provider里面接入本地的 granite3-dense:8b 模型。配置完成后在 TUI 里用/model切换就能看到这个本地模型。新版对 provider 的配置灵活度很高这也是它能同时接云端模型和本地模型的根本原因。4. 模型接入进阶Go 订阅、Codex、Ollama 与 Granite 的完整接法OpenCode 真正让人舒服的地方在于模型接入的灵活性。你既可以用官方订阅的托管通道也可以带上自己的密钥接入 Codex还可以在完全离线的环境里接 Ollama 上的本地模型。这一节我把自己试过的几种接法按场景拆开讲。4.1 opencode go 订阅计划怎么用如果你不想分别购买多个模型厂商的 API直接用 opencode 官方的 Go 订阅计划会比较省心。它相当于一个聚合通道订阅之后你不需要关心底层具体走了哪个模型的计费只管在 OpenCode 里切换模型就行。使用方式分两种。第一种是纯登录方式在 OpenCode 的 provider 里选择 opencode然后根据提示在浏览器里授权登录。第二种是密钥方式在 opencode 官网的账户后台生成 API 密钥然后把密钥填入 auth.json 或者环境变量OPENCODE_API_KEY中。两种方式我都试过稳定性和速度没有明显差别看你习惯哪种。对于已经买了订阅但不知道怎么连接的用户我建议先检查密钥是否写对了位置。在终端里运行echo $OPENCODE_API_KEY如果输出为空说明没有设置环境变量。用登录方式的话直接重新在 TUI 里选 provider 走一遍授权流程一般两分钟内能解决。另外Go 订阅计划里可以接入 Codex 模型选模型时注意不要选成旧版 Codex 的 experimental 通道选“codex”类目下的正式模型更稳定。这个细节在社区里经常被问我一开始也踩过切换到正式通道后就再没报错过。4.2 局域网访问opencode serve 的正确用法OpenCode 的 HTTP 服务模式非常适合局域网内共享能力。比如你有一台办公用的 Linux 服务器配置了模型通道其他同事的电脑可以通过局域网访问这台服务器上的 OpenCode 接口不用每台机器都配密钥。启动局域网服务的方式是opencode serve --hostname 0.0.0.0 --port 4096默认情况下opencode serve只监听 127.0.0.1也就是只能本机访问。要支持局域网访问必须指定--hostname 0.0.0.0。启动后其他设备可以通过http://你的IP:4096访问接口在浏览器里能看到一个简单的前端页面也可以用支持自定义 provider 的客户端比如 CC Switch指向这个地址。如果你希望服务在后台常驻我习惯用 systemd 或者 pm2 托管。以下是一个 systemd 服务文件示例[Unit] DescriptionOpenCode HTTP Server Afternetwork.target [Service] ExecStart/usr/local/bin/opencode serve --hostname 0.0.0.0 --port 4096 Restartalways User你的用户名 [Install] WantedBymulti-user.target注意把服务暴露到局域网意味着同一网段的其他机器都能访问。如果你的网络环境里有不信任的设备建议在服务前面加一层简单的访问令牌校验不要让端口裸奔。4.3 用 CC Switch 连接 opencode 再连接 ollamaCC Switch 是一个模型切换工具很多人喜欢把它和 OpenCode 串起来用做成本地模型统一入口。实际链路是CC Switch 作为客户端将请求转发给opencode serve暴露的接口再由 OpenCode 路由到 Ollama 上的本地模型。这样的好处是你的前端工具只需要配一个自定义 provider后端模型想换就换。具体配置分两步。第一步在 OpenCode 的配置里添加 Ollama provider确保 Ollama 的模型能通过 OpenCode 正常调用。第二步在 CC Switch 里新增一个自定义 Provider地址填http://OpenCode所在机器的IP:4096协议类型选 OpenAI 兼容格式模型名填你在 OpenCode 里配置好的模型名。保存后在 CC Switch 里选中这个 Provider就能把请求打到 OpenCode最终落到 Ollama 的本地模型上。这一步我踩过比较多的问题是连上了但模型一直报 404。排查思路是先确认 OpenCode 侧能不能正常调用 Ollama 模型opencode run hi --model ollama/granite3-dense:8b如果这条命令能正常返回说明 OpenCode 到 Ollama 的链路是通的。此时再去 CC Switch 里检查模型名是否和 OpenCode 配置里的模型名完全一致。注意CC Switch 侧填的模型名不是 Ollama 里的原始模型名而是 OpenCode 的 provider 配置中定义的模型 name很多人在这里写错。4.4 完全本地化OpenCode 接 Ollama 和 Granite如果你对数据隐私比较敏感或者有些代码根本不适合发给云端模型那就要走完全本地化的路线。OpenCode 接 Ollama 是目前最成熟的本地方案。以 IBM Granite 为例Granite 是 IBM 开源的代码生成模型在 Ollama 上可以直接拉取ollama pull granite3-dense:8b拉取完成后在 OpenCode 的opencode.json中配置 Ollama provider{ provider: { ollama: { baseURL: http://localhost:11434/v1, models: [ { name: granite3-dense:8b, aliases: [granite] } ] } } }配置完成后启动 OpenCode 并切换到ollama/granite3-dense:8b模型就能在没有外网的情况下完成代码生成、解释、重构等任务。本地模型的速度完全取决于你的机器算力。我实测 8B 模型在 32GB 内存的 M 系列芯片上响应很流畅日常改 bug 完全够用如果做大规模重构建议上更大的模型。提示本地模型和云端模型在使用体验上的差距主要在指令遵循和复杂逻辑推理上。简单任务生成单函数、解释代码、写测试用例本地 8B 模型表现很好跨多文件的深层重构仍然是云端大模型更稳。我的习惯是日常简单操作走本地大型重构走云端两个通道在 OpenCode 里切换模型也就几秒钟的事。5. 高频报错排查从 free tier 报错到模型列表为空使用过程中难免会遇到一些报错尤其在你尝试把 OpenCode 接入到其他工具、或者配置自己的 provider 时。下面几个问题是社区热搜里出现频率最高的我把原因和解决思路整理出来。5.1 error from provider (console): opencodes free tier can only be used from within opencode这个报错是很多人在用 CC Switch 或其他自定义客户端连接 OpenCode 时遇到的。报错的字面意思是opencode 的免费额度只能在 OpenCode 客户端内部使用。也就是说当你使用opencode serve或某种外部通道去调用 opencode 自带的免费模型时服务端会拒绝请求因为免费通道只允许在官方客户端内使用。出现这个报错后先不要慌。你需要确认自己是不是在用 opencode 官方免费模型作为 provider。如果你是通过外部工具比如 CC Switch调用 opencode serve 的接口而 OpenCode 内部使用的又是 opencode 的免费通道那这个报错是预期行为官方就是不允许这样转发使用。解决办法有两个方向一是换用你自己的 API 密钥接入其他 provider比如 OpenAI、Codex然后通过 serve 共享二是订阅 opencode 的 Go 计划用付费通道替代免费通道。付费通道不受这个限制可以正常被外部客户端调用。注意如果只是本地使用 OpenCode TUI 或桌面版几乎不会遇到这个报错。一旦你开始做局域网共享或者让其他工具来调 OpenCode 的接口就必须检查模型通道的性质。5.2 桌面版选择模型那里一个模型也没有了有用户反馈说打开 OpenCode 桌面版选择模型的下拉列表是空的。根据我排查的经验大概率是以下三类原因之一。第一配置文件被写坏了。桌面版会读取全局的opencode.json如果 JSON 格式错误或者 provider 配置缺失模型列表就加载不出来。排查方式是打开终端在任意目录下运行opencode看看 TUI 里能不能正常列出模型。如果 TUI 也是空的问题几乎可以确定在配置上。第二认证失效。如果你使用的是需要登录授权的 provider比如 opencode 官方通道token 过期之后模型列表会加载失败。桌面版侧重新登录一次即可或者在 auth.json 里更新密钥。第三Go 订阅计划到期或没有绑定密钥。Go 计划欠费/到期之后桌面端会呈现模型列表空的现象但在终端里往往会有更明确的报错信息。建议先跑一遍终端版把具体报错记下来再回桌面版处理。5.3 模型切换时提示 provider 未配置在 TUI 里输入/model切换模型时偶尔会遇到某个模型无法选择、提示 provider 未配置的情况。这通常是因为模型对应的 provider baseURL 没有写全。例如你只配置了模型名却没有配置 baseURLOpenCode 就不知道要把请求发到哪里。解决办法是打开opencode.json检查每个 provider 是否都有完整的baseURL和模型列表。特别是自定义本地模型时baseURL一定要写对Ollama 的默认地址是http://localhost:11434/v1如果你改了端口这里也要同步改。另一个容易忽略的是模型别名如果你在配置里加了aliases在 TUI 里切换时要使用别名而不是原始模型名。我不止一次在切换本地模型时发现找不到模型最后检查都是 aliases 和实际输入不一致。5.4 局域网客户端连接超时、页面打不开局域网访问opencode serve时常见的症状是本机能访问别的电脑访问不了。优先检查两个地方。一是监听地址是否真的绑到了0.0.0.0很多人在启动时漏了这个参数服务只对本机开放。二是有没有防火墙拦截 4096 端口Linux 上尤其常见。sudo ufw allow 4096/tcp如果开启了防火墙先放行对应端口再试。另外一点跨设备访问时建议直接用 IP 地址而不是主机名因为有些内网环境下主机名解析不稳定。我之前在办公网里就遇到过每次都解析超时的情况换成 IP 后立刻正常。5.5 常见问题速查表问题现象常见原因解决思路终端版正常桌面版模型列表为空桌面版配置与全局配置不一致在桌面版重新选择 provider或手动修复全局 opencode.json外部工具调用 opencode serve 报 free tier 错误使用免费通道做外部转发换用自己的 API 密钥或订阅 Go 付费通道CC Switch 连接 OpenCode 模型返回 404模型名与配置不一致在 OpenCode 配置中使用定义的模型 name而非原始模型名局域网其他设备无法访问 serve 端口监听地址或防火墙问题使用--hostname 0.0.0.0放行对应端口切换模型时找不到本地模型provider 未配置或别名错误补齐 baseURL确认别名正确历史会话找不到存储目录变更或误删查看~/.local/share/opencode/sessions用/sessions恢复安装后命令不存在PATH 未生效重开终端或手动把安装目录加入 PATH6. 我的一些个人经验和最后想说的实际操作中我发现OpenCode 这类终端 AI 代理工具真正提升效率的不是它支持多少个模型而是会话可恢复、文件可引用、Skill 可扩展、服务可共享这套完整的工作流。我现在每天的工作模式已经固定下来日常小改动用本地 Granite 模型快速跑一遍遇到大重构切换到 Codex 或云端模型通过/sessions随时恢复昨天没聊完的上下文。这个过程完全在终端里完成不打断编码节奏。最后分享一个小技巧在配置 Skill 的时候不要贪多先按自己团队最痛的一两个流程写起。比如我们最先写的commit 信息生成生效后紧接着写了代码审阅。每跑通一个 SkillOpenCode 的可用性就上一个台阶。相对于不停地研究新功能把已有的几个高频能力打磨稳定实际收益更大。这个经验是从我自己踩坑中得来的希望对你有用。