企业官网建设流程全解析

敢直接在终端里敲opencode的人，多半已经在 Claude Code、Codex CLI 里面折腾过一圈。我第一次在 Windows PowerShell 里敲完这个命令，屏幕直接甩回来一句“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名”，那一刻我就知道，这又是一款需要从头驯服的 AI 编程 agent。

严格来说，opencode 是一个开源、跑在终端里的 AI 编程 agent，重点落在“开源”和“终端”这两个词上。它不像 Cursor 那样是一个完整 IDE，也不像 Copilot 那样嵌在编辑器侧边栏；它和 Claude Code 更接近——你在命令行里描述需求，它自己读代码、改文件、跑测试、提交 Git。区别是 opencode 本身不绑定任何一家模型厂商，Claude、GPT、Gemini、本地模型都能接进来。如果你已经受够了单个厂商的额度限制，想找一套配置可控、模型自选、数据落在本地的方案，这篇文章基本就是为你准备的。

我会按实际使用顺序来写：先讲清楚它解决了什么问题，再把安装和初始化完整走一遍，接着聊模型接入、日常操作、skills 与 Playwright、编辑器插件，最后把我踩过的高频报错和排错思路整理出来。内容偏实操，命令和配置可以直接抄。

1. opencode 是什么：它凭什么从 Claude Code 手里抢用户

1.1 定位对比：opencode、codex、claude code 到底哪不一样

很多人在搜 opencode 的时候，会同时看到 Codex CLI、Claude Code、Gemini CLI 这些名字，因为大家解决的是同一类问题：让 AI agent 在终端里直接操作代码库。但它们的定位差别其实挺大：

我自己从 Claude Code 切到 opencode 的核心原因就一个：模型自由。Claude Code 体验再好，底层默认绑定 Anthropic 的模型，有时候你想在同样的流程里试一下其他模型，就要绕很多弯。而 opencode 的配置思路是“工具和模型解耦”——agent 框架是固定的，模型随便换。这种设计对于经常在不同项目里用不同模型的人来说非常舒服。

另外，opencode 的社区迭代速度非常快。原来用 TypeScript 写，后来团队直接重写成了 Go，启动速度和内存占用都提升明显。后面细说。

1.2 opencode go：用 Go 重写之后到底强在哪

“opencode go”这个说法在社区里出现频率很高，但很多人会误解成某个叫“go”的订阅套餐。其实它指的是 opencode 的 Go 语言版本。

早期版本基于 Node.js/TypeScript，安装以后依赖一堆 npm 包，跑起来还要等 Node 进程预热。后来团队决定重写，目标很明确——做成一个交付即用的原生可执行文件。重写完成之后的 opencode 直接给你编译好的二进制，单文件分发，没有 node_modules，启动速度基本是秒开。

实际体验下来，体感差异最明显的是两个场景：

1. 在 CI/SSH 远程机器上使用。以前还要确保目标机器有 Node 环境，现在直接丢一个 binary 进去就能跑，省了很多环境问题。
2. 长时间会话下的内存占用。Node 版跑大项目，agent 上下文一多，内存动不动几百 MB；Go 版本明显更稳，日常会话基本在一百多 MB 以内。

另外，新版安装脚本也更简单了。只要执行官方的一行命令，它会自动判断系统和架构，下载对应的二进制到你本机目录。这一点对新手很友好。

1.3 TUI 界面：第一次打开别慌

opencode 的界面是典型的 TUI（Terminal User Interface，终端图形界面）。我第一次打开的时候，面对满屏的分栏有点懵，但用熟之后觉得它比纯 CLI 强太多——因为它始终在告诉你“当前 agent 正在做什么”。

大致布局可以这样理解：

• 左侧是会话历史列表，方便在不同任务之间切换。
• 中间是对话区，模型输出、工具调用、命令执行结果都会流式显示出来。
• 底部是输入框，支持普通文字输入，也支持以/开头的斜杠命令。

常用命令我建议先记这几个：

• /help：查看内置命令列表，包括 /models、/sessions、/init 等，相当于所有文档的入口。
• /models：查看当前配置了哪些模型，可以直接切换。
• /sessions：查看历史会话列表，回过去找之前某个任务。
• /undo：撤销 agent 最近一步操作，这个比 Ctrl+Z 更精确，它撤销的是 agent 层面的文件变更。
• Esc或Ctrl+C：中断当前输出，注意不会马上终止整个进程，通常会进入“是否确认停止”的状态。

TUI 存在的意义不是花哨，而是让你在 agent 自动操作文件、跑命令的时候有足够的可控感。你永远看得到它下一步要干什么，再决定是放行还是打断。这也是我后来更愿意在终端里用 agent 而不是在网页编辑器里拖拽的原因。

2. 安装与初始化：把 opencode 跑起来的第一步

2.1 三条安装路线：curl、npm、brew 怎么选

opencode 官方提供了几种安装方式，选择主要看你平时习惯用哪个包管理器。

我个人的建议是：macOS 用 brew，Linux 和 Windows 优先用官方脚本，Windows 上如果不想折腾 bash，直接 npm 也可以。

这里要说一个从热搜词里就能看出的高频问题：很多人执行完官方安装脚本后，在 PowerShell 里运行opencode报“无法识别”。这是 Windows 下 PATH 环境变量的经典坑，我下面展开讲。

2.2 报错“无法将 opencode 项识别为 cmdlet”的完整排查链路

这个报错的完整文本是：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果存在路径，请确保路径正确，然后再试一次。

出现这个错误，本质是 PowerShell 在环境变量 PATH 所列目录里找不到opencode.exe这个可执行文件。但为什么明明“装好了”却找不到？我踩过之后梳理了几个常见原因：

原因 1：安装脚本只写入了当前 shell 的 PATH，没有写进系统环境变量。
官方脚本或 npm 在安装结束后，通常会提示“please restart your terminal”或者直接修改当前 shell 的配置文件。如果你用的终端会话是在安装之前就打开的，PATH 不会自动刷新。第一步永远是重开一个终端窗口再试。

原因 2：npm 全局目录不在 PATH 里。
在 Windows 上，npm 全局安装的包通常放在%APPDATA%\npm目录。这个目录默认是在 PATH 里的，但如果你装过多个 Node 版本（nvm-windows、fnm 等），PATH 被改来改去，可能就丢了。可以用下面命令确认：

npm prefix -g

它会输出 npm 全局目录的真实位置。然后你手动把这个目录加进 PATH 即可。

原因 3：安装工具并不是装到了 Windows 本机，而是装进了 WSL。
如果你是在 WSL 的 bash 里执行的安装命令，那opencode只存在于 WSL 内部。外面 Windows 的 PowerShell 是完全独立的另一个系统，当然找不到。这种情况你需要在 WSL 终端里使用，或者在 Windows 侧重新装一份。

排查路径我整理成一套可复现步骤：

1. 先确认安装产物是否真的存在。官方脚本默认装到~/.opencode/bin；在 PowerShell 里检查：

   Test-Path "$env:USERPROFILE\.opencode\bin\opencode.exe"

2. 如果文件存在，手动将这个目录加入用户 PATH：

   setx PATH "$env:USERPROFILE\.opencode\bin;$env:PATH"

   提示：setx有 PATH 长度上限（通常是 1024 字符），如果 PATH 已经很长，可能会截断。更稳妥的做法是通过“系统属性 -> 环境变量”图形界面编辑，避免破坏已有路径。

3. 重开终端，验证：

   opencode --version

这套排查流程不仅适用于 opencode，你以后装任何命令行工具遇到“cmdlet 无法识别”都可以套用：先确认文件在不在，再确认目录在不在 PATH，最后刷新终端，三步定位。

2.3 首次启动：登录选模型还是直接填 API Key

安装好之后，直接在终端输入：

opencode

首次启动会进入模型接入引导。新版后台会让你选择 Provider，然后跳转浏览器完成登录，或者让你粘贴 API Key。如果你不想每次都被引导打断，更推荐直接用环境变量配置：

export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-..." export GEMINI_API_KEY="..."

Windows PowerShell 里对应写法：

$env:ANTHROPIC_API_KEY="sk-ant-..."

配置完成后，opencode 会把凭据保存在本机配置目录（macOS/Linux 是~/.config/opencode/，Windows 是%USERPROFILE%\.config\opencode\），不需要每次都输入。

如果你同时配置了多家模型的 Key，启动后用/models命令就能看到所有可用模型，直接用方向键切换。

2.4 验证环境：几行命令快速自检

我的习惯是装完任何工具都先跑一遍自检流程，能省掉后面排查的一堆时间。opencode 的自检包括：

opencode --version # 版本是否正常 opencode run "Reply with OK" # 非交互式跑一个最简单的任务

第二条命令很有意思，它不启动 TUI，而是直接以单次任务模式运行。如果它能输出OK，说明安装、PATH、API Key、模型服务整条链路都是通的。我强烈建议你在完全打开 TUI 之前先跑这一条，因为一旦进 TUI，如果模型服务有问题，界面卡在那里，报错信息反而不如命令行直观。

3. 模型接入与选择：同一个任务，不同模型差距有多大

3.1 官方支持的供应商与接入方式

opencode 模型接入的设计思路很开放，我总结下来有四类：

第一类：官方直连供应商。Anthropic、OpenAI、Google Gemini 都支持，只要设置对应的环境变量 Key 就能用。

第二类：本地模型。通过 Ollama 等本地推理服务接入。配置好 Ollama 地址（默认http://localhost:11434），opencode 就能识别本机已经拉取的模型列表。好处是数据完全不出本机，而且没有按量计费。

第三类：OpenAI-compatible 兼容端点。这应该是 opencode 最强大的能力之一。只要某个模型服务提供了兼容 OpenAI 接口格式的 API，你就能把它配进 opencode 当模型用。配置方式是在opencode.json里的 provider 字段指定baseURL和模型名。

第四类：社区维护的 Provider 列表。opencode 社区沉淀了一批现成的 provider 配置模板，你在/models里能看到不少选项，选中的时候它会自动填入默认配置。

3.2 实测建议：重活、轻活、免费活别混在一起

我自己用下来的一个核心体会是：不要指望一个模型解决所有问题。opencode 的价值恰恰在于切换模型足够简单，这让我可以按任务类型灵活选择。

这里有个很现实的点：旗舰模型虽然强，但在大规模项目里反复读文件、改几十处代码的时候，token 消耗是肉眼可见的。把“重活”和“轻活”分开，能明显降低账单。

3.3 配合 CCSwitch 管理多套 Key 和端点

很多人的 Key 不是只有一家的：项目 A 用官方账号，项目 B 用公司共享账号，还有本地测试用的端点。每次切换都要改环境变量，非常烦。社区里有个开源小工具叫 CCSwitch，就是专门解决这个问题的。

CCSwitch 的使用逻辑很简单：

1. 打开工具，选择你要切换的对象是 Claude Code 还是 opencode。
2. 在里面维护多套供应商配置，每套包含名称、BaseURL、API Key、默认模型。
3. 一键切换到某个配置，它会把对应参数写入 opencode 的配置文件或环境变量。
4. 重新打开 opencode 就生效了。

在我看来，opencode 本身就支持 provider 配置，所以 CCSwitch 不是必需品，但如果你同时维护很多套 Key，它确实能把“改配置”这个动作从每分钟变成一秒。特别是调试模型服务出问题的时候，快速切换备用端点能节省大量时间。

3.4 免费模型和订阅方案，怎么选才不坑

热搜里“opencode 免费模型”这个词热度很高，我的建议是：

免费的本地模型（比如 Ollama 拉下来的开源模型）非常适合拿来跑通流程。你第一次用 opencode 不知道命令怎么玩、TUI 怎么操作，用本地模型当“陪练”完全够用，而且不用花一分钱。我一开始就是用本地模型学会了 skills 的写法。

但真正进入生产环境干活，免费模型和旗舰模型的差距还是很明显。最典型的区别是长任务稳定性：旗舰模型能持续记住你最初定下的目标，而免费/小模型经常干到一半“忘记”任务背景，开始自作主张改一些不该改的文件。这种返工成本，往往比省下的那点 API 费用高得多。

如果需要订阅付费方案，建议先跑两个星期免费/按量付费，看自己的 token 消耗量级再决定。我见过太多人一上来就订阅最高档，结果每个月实际用量连十分之一都不到。

4. 日常开发工作流：从改 bug 到跨文件重构

4.1 第一个真实任务：修复一个失败的测试

前面铺垫了这么多，终于到真正干活的部分。我在一个新项目里第一次用 opencode 修 bug 的场景还挺有代表性：

项目里有个 Python 测试文件test_auth.py，其中一个用例test_login_failure跑挂了。报错信息说断言失败，但我一时看不出是前端传参问题还是后端逻辑问题。

我直接在 opencode 里输入：

看一下 tests/test_auth.py 里 test_login_failure 为什么失败，帮我修复它，然后运行 pytest tests/test_auth.py -k test_login_failure 验证。

注意最后那句“跑什么命令算验证通过”很重要，这是给 agent 一个明确的验收标准。opencode 收到任务后的动作是：

1. 读取测试文件。
2. 追踪被测试的login函数。
3. 发现是异常场景下error_code字段拼写错误。
4. 修改源码。
5. 运行我指定的 pytest 命令。
6. 输出测试通过的结果，并说明原因。

整个过程里，它每跑一个命令之前都会在 TUI 里显示出来，我可以选择放行或中断。这种“人审阅、agent 执行”的节奏，是我认为 AI 编程 agent 最正确的用法——不是全自动放任，也不是纯手动，而是人在关键节点把关。

4.2 多文件改动、批量重构和 Git 提交的节奏

当任务从“修一个测试”升级到“重构整个模块”时，要格外注意节奏控制。我总结了两个原则：

原则一：用显式边界约束改动范围。比如你要重构src/services下的请求封装，prompt 里要写明“只动 src/services 目录下的文件，不要改其他目录”。不然 agent 很可能为了“让逻辑更一致”，顺手把调用方也改了，diff 范围瞬间失控。

原则二：把改代码和提交 Git 分成两步。我见过一些配置默认让 agent 自己 commit，这在简单项目里没问题，但复杂项目里它的 commit message 经常写得过于笼统。我的习惯是：

1. 第一阶段 prompt：让 agent 改代码，但明确要求“不要提交”。
2. 人工执行git diff审查改动。
3. 第二阶段 prompt：让 agent “根据当前 diff 写一个规范 commit message，然后执行 git add + git commit”。
4. 如果项目有 pre-commit hook，让它跑完以后自动修正 lint 问题。

这套节奏既保留了 agent 的高效，也保住了代码审查的底线。

4.3 上下文工程：哪些文件该塞给它，哪些不要

opencode 默认会读取你当前项目结构，但它不是每时每刻都在读所有文件。真正决定 agent “懂不懂你的项目”的，是你给了它什么上下文。

我总结了一个经验公式：精确指定 + ignore 排除 > 让它自由探索。具体来讲：

• 在 prompt 里用@文件路径的方式直接指定关键文件，比如@src/config.ts 里导出的 CONFIG 对象字段有哪些。
• 在.opencodeignore或者配置里排除node_modules、dist、build、vendor这些非源码目录，防止 agent 在无关文件上消耗上下文窗口。
• 开场先给一句话项目背景：“这是一个 Next.js 14 项目，接口层在 src/api，数据库模型在 prisma/schema.prisma。” agent 有了地图，探索效率会高很多。

为什么这段重要？因为 agent 的上下文窗口是有限的。当对话越来越长，窗口越满，它“忘事”的概率就越高。如果你一上来就丢了几十万 token，让它在垃圾信息里找重点，任务就已经失败一半了。

4.4 LSP：让 agent 不只是“读代码”，而是真正“理解代码”

很多人把 LSP 理解成“编辑器的跳转功能”，但在 opencode 里，LSP 是让 agent 更聪明地改代码的关键。

LSP（Language Server Protocol，语言服务器协议）的价值在于：它能给 agent 提供语义层面的信息，比如某个函数在哪里定义、哪些地方引用了它、当前类型是否匹配。没有 LSP，agent 只能靠正则和文本相似度去猜；有了 LSP，它改完函数签名之后，能自动感知哪些调用点需要一起修。

我遇到过最典型的一个场景：重构一个 TypeScript 接口字段名。如果没有 LSP，agent 可能只改了接口定义本身，把所有调用点漏掉；配置了 LSP 之后，它在命令行里输出“检测到 12 处引用需要同步更新”，然后逐一处理。

在opencode.json里可以自定义 LSP 服务器地址。常用的有：

• TypeScript / JavaScript：typescript-language-server
• Python：pyright-langserver
• Go：gopls

配置方法是在配置文件的lsp字段里指定命令。需要注意，首次启动 LSP 会扫描项目建立索引，大规模项目会有点吃内存，不用的时候可以关掉对应语言的 server，用到再开。

5. skills 和 Playwright：给 opencode 加“技能”和前端调试能力

5.1 skills 机制：一个 SKILL.md 到底长什么样

skills 是 opencode 的一个核心扩展机制。你可以把它理解成“给 agent 预装的一套操作手册”：当它遇到某种类型的任务时，会自动加载对应手册，按里面的步骤执行。

一个 skill 本质上就是一个带特定结构的 Markdown 文件，放在规定目录下：

.opencode/skills/<skill-name>/SKILL.md

内容结构长这样：

--- name: code-review description: 在提交代码前对当前改动进行审查，检查潜在 bug、安全隐患和性能问题。 --- # Code Review 当用户说“review”“审查代码”“提交前检查”时，执行以下步骤： 1. 运行 git diff，查看当前工作区改动。 2. 逐文件检查： - 是否存在未处理的异常 - 是否引入安全风险（如 SQL 注入、XSS） - 是否有明显性能问题 3. 输出审查结论，给出修改建议，但不要直接改代码。

这里的核心是description字段。agent 会基于它对用户输入进行意图匹配，如果 description 写得太模糊（比如“处理代码问题”），它反而不知道该什么时候触发。写清楚触发场景和触发词，skill 才实用。

5.2 写一个项目专属 skill：从需求到生效

举一个实际例子。我有个前端项目经常需要排查页面渲染问题，于是我写了一个 skill，让 opencode 一遇到“页面怎么坏了”“帮我看看这个前端 bug”就自动走一套固定流程：

--- name: frontend-debug description: 排查前端页面 bug 时使用。包括启动本地服务、用 Playwright 打开页面、查看浏览器 console 错误、定位问题文件。 --- # Frontend Bug Debug 当用户报告前端 bug 或请求检查页面时： 1. 确认本地开发服务是否已启动；未启动则先运行 npm run dev。 2. 用 Playwright 打开对应页面 URL。 3. 等待页面加载，获取 console 日志和 network 错误。 4. 截图保存到 /tmp/debug-screenshot.png，并把截图路径告诉用户。 5. 根据错误堆栈定位源码文件，分析原因后给出修复建议。

这样写完之后，skill 文件放进项目的.opencode/skills/目录，并提交到 Git。团队其他人克隆项目之后，也自动拥有这个能力。

5.3 用 Playwright 复现前端 bug 的完整链路

我自己用 opencode 加 Playwright 排查过一个很典型的“按钮点击无反应”问题，整个过程让我对前端自动化调试信心大增。当时页面里有个登录按钮，点击后完全没反应，Console 里也不报错，从静态代码上很难一眼看出问题。

opencode 配合 Playwright 的处理链路是：

1. 启动本地开发服务器。
2. 用 Playwright 打开页面。
3. 自动点击那个登录按钮。
4. 打印 console 日志和 network 请求列表。
5. 发现点击事件里调用了window.handleLogin()，但这个函数在某个脚本加载失败后没有被定义。
6. 定位到脚本引入顺序的问题，修复后重新跑一遍验证。

整个过程里最花时间的反而不是 agent 的操作，而是它每执行一步都要和我确认。如果你确认任务风险不高，可以在配置里允许它自动执行部分命令，效率会高很多。

需要注意 Playwright 本身需要安装浏览器运行环境。在服务器或 CI 里跑的时候要设置 headless 模式，避免因为没有图形界面而启动失败。

5.4 skill 没生效的常见原因

我遇到过几次写好了 skill 但 agent 完全无视的情况，总结下来主要是这几个原因：

• 文件名或目录位置不对。必须是.opencode/skills/<名称>/SKILL.md，直接放SKILL.md在根目录不生效。
• description 写得太泛。agent 匹配意图的时候需要足够明确的触发条件。
• 改完 skill 没重启会话。对话进行中修改 skill 文件，当前会话不会自动加载，需要开启新会话。
• 项目里配置了 ignore 规则，把 skills 目录排除了。检查一下.opencodeignore内容。

6. 编辑器集成：VSCode 和 IDEA 里的 opencode

6.1 VSCode 插件：和终端里的 opencode 是什么关系

很多人的第一反应是问：VSCode 里的 opencode 插件是不是另一个工具？其实不是，它本质上是终端版 opencode 的“可视化远程控制台”。

安装官方扩展后，VSCode 侧边栏会出现 opencode 面板。它会连接到你本机的 opencode 服务，复用同一个配置和会话历史。也就是说，你在终端里开到一半的会话，可以在 VSCode 面板里继续，反之亦然。

我实际使用中觉得最实用的功能是把选中代码直接带入对话。在编辑器里框选一段代码，右键选择“发送到 opencode”，它会把代码片段、文件路径、当前光标位置一起传给 agent，省去手动引用文件的步骤。

这个插件适合“边读代码边对话”的场景：左边是编辑器，右边是和 agent 的对话面板，看到哪问到哪。

6.2 JetBrains IDEA 插件：老牌 IDE 用户怎么接

JetBrains 家族的插件（IDEA、PyCharm、GoLand 等）也已经有官方实现了。功能逻辑和 VSCode 插件类似，都是面板集成。

需要注意的一点是版本匹配：IDEA 插件版本和 opencode CLI 版本不一致时，很可能出现连接失败或功能按钮异常。具体表现是面板一直转圈、提示 session host not found 之类。遇到这种情况，把两个端都更新到最新版，问题基本能解决。

IDEA 插件对 Java/Kotlin 项目的支持体验比较自然，因为它能和 IDEA 内置终端联动。我个人的建议是：如果你主力 IDE 是 JetBrains 系，先直接用内置终端跑 opencode，插件作为辅助参考，不必依赖。

6.3 我的混合工作流建议

用了一段时间之后，我形成了固定的工作方式：

• 深度任务在终端 TUI 里跑。涉及多文件重构、自动跑测试、连续执行命令的任务，TUI 的可控性和信息密度更高。
• 读代码和提问在 VSCode 面板里做。比如看一个不熟悉的模块，选中代码问 agent“这段逻辑有没有问题”，比来回切窗口舒服。
• 同一个项目不要同时开两个会话。我在终端开了一个会话，又用 VSCode 面板开另一个，两边同时操作同一个文件，结果出现了互相覆盖的情况。后来就默认“一个项目同时只保留一个 opencode 会话”，要么终端，要么编辑器，不并行。

7. 高频报错现场：这些坑我替你踩过了

7.1 error: unexpected server error. check server logs

这是 opencode 用户最常遇到的报错之一，原文是：

error: unexpected server error. check server logs

大多数人看到这个第一反应是重试，但实际上这个报错的本意是：opencode 向模型服务端发起了请求，但服务端返回了一个它无法解析的异常。要解决它，关键是先搞清楚是哪一端出了问题。

我的排查顺序是：

1. 确认 API Key 有效且没有过期。这是最高频的原因。很多 Key 在后台面板看着是“活跃”的，实际上因为欠费或权限变更已经没法用了。
2. 确认网络连通性。用 curl 直接访问一下对应模型服务的 API 域名，看能否正常响应。这一步能快速排除“本地网络到服务端不通”的问题。
3. 查看服务商状态页。如果服务商正在出事故或维护，那就不是你能控制的了，等恢复即可。
4. 检查本地模型服务（如果用的是 Ollama）。执行ollama list和ollama ps看模型是否加载成功，连接是否正常。Ollama 更新版本后 API 有变化，也可能导致 opencode 连不上。
5. 重置 opencode 进程。某些异常会导致本地状态卡住，杀掉进程重开通常能恢复。

整套流程下来，基本能定位百分之九十的问题。

7.2 提示模型不可用（this model is not available...）怎么办

有时候你会看到类似这样的报错：

This model is not available in your country.

这个提示本身说明模型服务商对指定模型设置了开放范围限制，你当前的 API 账号所在区域不在支持列表内。遇到这种情况，我的处理顺序是：

1. 确认当前 prompt 用的是哪个供应商的哪个模型，登录服务商后台看该模型的支持范围。
2. 切换到服务商明确开放的其他模型。比如某些旗舰模型不可用，但同系列的中端或旧版本模型仍然可用。
3. 如果团队确实需要某个受限模型，可以在 opencode 里配置另一家合规供应商的等价模型，不影响 workflow。
4. 不要轻易相信网上那些“非官方渠道接入”的方案。这类方式既不稳定，还容易触发 API Key 风控，导致更严重的封禁问题。

从工程角度讲，模型不可用只是“供应商选择”层面的问题，换一个供应商或者换一个等价模型就够了。opencode 的价值恰恰在于切换模型成本极低，所以不用非得死磕某一个模型。

7.3 手动编辑 opencode.json 的注意点

opencode 的配置文件opencode.json放在项目根目录或全局~/.config/opencode/下。手动编辑的时候有几个坑：

JSON 不允许注释。很多习惯了 JSONC（带注释的 JSON）的人会顺手写//注释，结果 opencode 直接拒绝加载配置。我建议只在外部记录文件里写说明，配置本身保持纯净。

路径写绝对路径。配置里涉及目录的字段，尽量写绝对路径，或者先确认相对路径是相对于项目根还是配置文件所在目录，避免跨机器同步时路径失效。

改完要验证。改完配置后，先跑opencode --version或随便跑一条opencode run确认没有语法错误。我自己踩过的最大坑是手滑在某个字段后面多加了一个逗号，导致配置完全没加载，但命令本身不报错，只是行为始终不对，排查了很久。

7.4 升级与回退：版本太快也有烦恼

opencode 的迭代速度非常快，我用的时候还是早期版本，写这篇时已经有人提到 2.0 了。快速迭代带来的最直接问题是：配置文件格式、命令行为可能在不同版本之间发生变化。

我建议在生产环境里锁定版本。如果你用 brew 安装，可以在升级前看当前版本的配置快照；如果是二进制方式安装，升级之前备份opencode.json和 skills 目录。遇到新版本配置不兼容的问题，不要硬着头皮适配，直接回退到上一个稳定版本，等社区的迁移文档出来再升。

最后：我当前的配置组合和一个实用习惯

写到这里，分享一个我现在固定的配置组合，供你参考：

• 主力模型用旗舰款处理复杂任务，日常小改动切到中端或开源模型。
• Ollama 本地跑一个小尺寸模型，负责零散的问答和日志解释，不消耗外部 API 额度。
• 用 CCSwitch 维护多套 Key，切换的时候不用碰配置文件。
• opencode.json 和 skills 目录全部放进 dotfiles 仓库，新机器一条脚本就能恢复完整环境。

还有一个我特别推荐的习惯：把 opencode.json 放进项目的版本控制里。这样同一个项目无论谁接手，打开 opencode 就能得到一样的模型配置、LSP 设置和 skills。你不需要写长篇 README 告诉新人“要用哪个模型、别动哪些文件”，配置文件本身就是最好的文档。

opencode 这个工具给我最大的感受是：AI 编程 agent 不该被某一家模型厂商绑架。工具负责流程，模型负责智能，两者自由组合，才是这套玩法真正的潜力。如果你也在选终端 agent，希望这篇内容能帮你少走一些弯路。