企业官网建设流程全解析

2025 年如果你还在为切换大模型 Key 而反复改环境变量，那你大概率已经听说过 opencode；如果还没听说过，那你很快会在某个技术群看到有人贴出一整屏漂亮的终端界面，里面 AI 正在自己读代码、跑测试、修 bug。我第一眼看到 opencode 时以为它只是又一个 Claude Code 的套壳工具，直到我把它装进一个半年没动过的老项目里，看着它把 Maven 构建错误一条条捋清楚，又在 Playwright 里复现了一个我盯了很久的前端诡异 bug，我才意识到这个开源终端 AI 编程代理的分量。这篇文章不是简单的功能介绍，而是把我从安装、配置、插件、桌面版到真实项目排查踩过的全部坑，一次说清楚。

1. 从"cmdlet 无法识别"报错说起：opencode 到底是什么，谁在维护它

1.1 它解决什么问题

Claude Code 把终端 AI 编程带出圈之后，很多人一边爽一边难受：闭环生态、模型绑定、配置文件不够开放，想接入自己的模型或本地服务时尤其别扭。opencode 就是在这样一个诉求下出现的开源替代品——它做的是同一件事：在终端里跟你以对话方式协作，读项目结构、改文件、执行命令、跑测试，但不一样的地方在于它天生就是开放的。

核心能力拆开看主要有三块。第一，多模型接入，Anthropic、OpenAI、Gemini、DeepSeek、Ollama 本地模型都能用，只要它是 OpenAI 兼容接口就能接进去；第二，原生 TUI（终端交互界面），不是简单的命令行问答，而是带会话管理、diff 预览、多文件修改的完整终端工作台；第三，可编程的扩展体系，支持 Skills、MCP、AGENTS.md 记忆机制，能针对不同项目单独调校它的行为。

它适合谁？我觉得是这么三类人：一是对 Claude Code 贵且绑定不满，想保留终端 AI 编程体验但想自由选择模型的人；二是要在本地或私有环境里接模型，不希望代码提交到第三方服务的团队；三是想在编辑器之外用一个更专注、更少干扰的 AI 编程界面的人。如果你只是偶尔让 AI 写一小段函数，那 GUI 客户端就够用，opencode 的优势体现不出来；但如果你每天有大量时间在终端里看代码、跑构建、查日志，它会很快成为主力入口。

1.2 不是哪家公司的商业产品，但背后有成熟的开源团队

很多热搜词在问"opencode 是哪家公司的"。答案可能和你想的不一样：它不是某家云厂商的商业产品，而是一个开源项目。当前代码托管在 sst/opencode 仓库，和做 serverless 框架的 SST 团队有紧密关系，同时有大量社区贡献者参与。这意味着它的迭代速度非常快，但也意味着你要有"功能变动跟着版本走"的心理准备。

和 Claude Code 对比更容易理解它的位置。Claude Code 是闭源的，深度绑定 Claude 模型，订阅制价格固定，好处是开箱即用、官方维护；opencode 是开源的，你想接哪个模型就接哪个，成本完全取决于模型 API 的定价，坏处是配置自由度高，初期需要自己搭环境。Codex 则是 OpenAI 官方的终端 Agent，和 GPT 生态绑定，风格更偏向自动执行任务。后面我会专门放一张对比表，这里先记住结论：opencode 的核心价值就是不绑架，想换模型、想改行为、想加插件，都拦不住你。

1.3 上手门槛比想象低，但环境坑一个不少

尽管它是一条命令就能装的工具，真正让新手卡住的往往是那些老掉牙的环境问题：Node 版本、PATH 路径、认证方式、配置文件格式。接下来的篇幅，我会把安装到排查的全流程拆开，每一个报错都给出完整的定位思路，而不是只给一句"重装试试"。

2. 安装不是只有 npm 一条路，但这两个环境坑绕不开

2.1 官方三种安装方式怎么选

opencode 的官方安装方式现在主要有三种，我分别说清楚适用场景。

macOS 用户最简单，Homebrew 直接装：

brew install sst/tap/opencode

Linux 和 macOS 都可以用官方脚本：

curl -fsSL https://opencode.ai/install | bash

Windows 用户要么用 scoop，要么用 npm：

scoop install opencode

npm install -g opencode-ai

这里有个特别容易踩的初级坑：npm 包名是 opencode-ai，不是 opencode。因为 npm 上 "opencode" 这个短名字早被别的项目占用了，官方只能注册带后缀的包名。很多人照着文档敲npm install -g opencode，装完发现命令不存在的确会懵。

如果你已经有 Node 18+ 环境，我个人的建议是无脑走 npm。原因很简单：版本更新最直接，npm install -g opencode-ai@latest就能升级，不需要等 Homebrew tap 同步。Homebrew 的方案更适合那些不想装 Node 或者希望跟系统包管理统一的用户。官方脚本的方案最省事，但如果你对 pipe 到 bash 的安装方式有顾虑，那还是用 npm 吧。

注意：无论哪种方式，都不建议加 sudo。如果遇到权限问题，优先检查 npm 的全局目录归属，而不是用 sudo 强行装。

2.2 Windows PATH 问题：完整的 cmdlet 报错排查过程

热搜里排名非常靠前的报错是这句：

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

这个报错其实是 Node 生态在 Windows 上的老问题，和 opencode 本身无关。npm 把全局可执行文件装到了某个目录，但 PowerShell 不知道去那里找，就会报"识别不了"。

排查步骤我建议这样走：

第一步，确认 npm 全局目录到底在哪：

npm config get prefix

以 Windows 默认配置为例，通常是C:\Users\你的用户名\AppData\Roaming\npm。你打开这个目录，里面应该能看到opencode和opencode.cmd这两个文件。看到它们就说明安装本身成功了，只是 PATH 没配上。

第二步，打开系统环境变量设置。Windows 搜索里输入"编辑系统环境变量"，打开后点"环境变量"，在"用户变量"里找到Path，点编辑，新增一行：

%APPDATA%\npm

注意用户变量不是系统变量，除非你的 npm 配置在系统级目录，否则别去动系统变量。

第三步，关掉所有已经开着的终端窗口，重新打开一个新的 PowerShell。这一步非常关键，因为 PATH 的更新不会自动注入到已经打开的终端会话里。很多人在旧窗口里试了半天，重启电脑才发现新窗口里早就好了。

验证命令：

opencode --version

如果还是不行，再看两个地方：一是确认 Node 是否真的装了，运行node -v；二是确认你是不是把包装到了其他 prefix 下，比如 nvm 管理的多个 Node 版本之间切换可能导致命令找不到，切回去就行。

提示：如果你用的是 Cmder、Git Bash 这类第三方终端，PATH 的加载逻辑可能和原生 PowerShell 不太一样，出现同样的报错时先切到 PowerShell 验证，能帮你有更好的方向定位。

2.3 安装后必做验证和版本管理

安装完成只是第一步。我建议任何环境的用户都先跑一遍基础的验证链路：

opencode --version opencode --help

--version确认版本号，--help确认命令能被正确解析。如果两步都正常，说明基础安装没问题，后面遇到任何模型层面的报错，就不会怀疑到安装环节。

版本管理上面，opencode 的迭代非常活跃，新功能基本都是跟着版本走。我的经验是：主力开发环境不要追太新的版本，等社区跑几天再升；但也不能长时间停在旧版，否则 schema 配置格式变了你都不知道。看到它能直接升级时，顺手做一次也不亏。

3. 把模型接进来：auth、配置文件与免费模型的正确接入姿势

3.1 认证逻辑：auth login、环境变量和 auth.json 的关系

装好 opencode 之后，第一个要解决的就是模型认证。它支持三种方式，先搞清楚它们的优先级和关系，后面报错才好判断原因。

第一种是交互式登录：

opencode auth login

它会列出支持的服务商，选中后会打开浏览器完成 OAuth 授权，授权完成后把凭证写到本地 auth 文件里。

第二种是环境变量。opencode 会自动读取常见的模型服务商变量，比如ANTHROPIC_API_KEY、OPENAI_API_KEY，你只要设置了，它就直接用，不需要额外登录。

第三种是直接编辑配置文件，把 key 写在 provider 配置里。这种方式最灵活，适合自定义端点或本地模型。

很多人的困惑是：这三种都配了，到底以哪个为准？我的理解是，环境变量和交互式登录的作用范围不同，而配置文件里明确写了 apiKey 的，会优先用于对应的 provider。如果出现"我明明设置了 ANTHROPIC_API_KEY 但还是告诉我没有 key"，十有八九是你用了自定义 provider 但配置文件里没把 key 传进去，或者 key 里带了空格、换行符。

3.2 自定义 Provider 与本地 Ollama 模型接入示例

opencode 的配置文件是项目根目录或全局用户目录下的opencode.json。我第一次配置时在 schema 上卡了一阵，后来发现关键是理解三段式结构：npm 代表这个 provider 用哪套 SDK，options 代表连接参数，models 代表要暴露哪些模型。

接一个 OpenAI 兼容的自定义端点，配置长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "myendpoint": { "npm": "@ai-sdk/openai-compatible", "name": "My Endpoint", "options": { "baseURL": "https://api.example.com/v1", "apiKey": "{env:MY_API_KEY}" }, "models": { "my-model": { "name": "My Model" } } } } }

注意apiKey我写的是{env:MY_API_KEY}，这是让 opencode 从环境变量里读取，而不是把 key 直接写死在配置文件里。配置文件如果被提交到 Git，key 就泄露了，这个习惯要早点养成。

接本地 Ollama 更简单，因为 Ollama 本身也提供了/v1的 OpenAI 兼容接口：

{ "provider": { "ollama": { "npm": "@ai-sdk/openai-compatible", "name": "Ollama Local", "options": { "baseURL": "http://localhost:11434/v1", "apiKey": "ollama" }, "models": { "qwen2.5-coder:7b": { "name": "Qwen 2.5 Coder 7B" } } } } }

Ollama 的 apiKey 随便填一个占位符就行，它根本不校验。配置好后启动 opencode，用--model指定模型 id，格式是provider/模型名：

opencode --model ollama/qwen2.5-coder:7b

第一次跑本地模型你会明显感觉到响应比云端模型慢，但在断网环境、隐私要求高的项目里，这套链路是能真正干活的。

3.3 关于"免费模型"和第三方端点的一句话忠告

热搜里有一个词是 "opencode 免费模型"，还有 "hy3-free 下线了吗"。这两件事其实是一体两面。社区里隔三差五就会冒出一些名字看着像免费通道的第三方端点，传得快、凉得也快。今天还能用的，可能下周就返回 5xx，或者干脆链接失效。

我的态度很明确：这些端点只适合临时体验，绝不能写进日常使用的配置文件。如果你正在用某个第三方免费端点，某天突然遇到unexpected server error，第一反应不要怀疑 opencode 坏了，先去看是不是端点挂了。把配置切回官方服务商或者本地模型，用排除法定位问题来源，这是最快的解决路径。依赖免费端点做正经项目，就像把房子盖在沙地上，随时可能塌。

3.4 2.0 之后的配置格式演进

opencode 进入 2.x 时代之后，配置文件的 schema 比早期版本规范了很多。早期版本各版本的 provider 写法不统一，网上搜到的老教程经常对不上号。现在统一以opencode.json为准，并且文件头建议带上$schema字段，这样在 VSCode 等编辑器里写配置时能获得字段校验和补全，减少低级错误。

如果你是从旧版本升上来的，升级后如果发现模型列表异常，优先检查 provider 的options和models这两个字段是否符合现在的三段式结构。社区里很多"升完级模型全没了"的求助帖，基本都是字段名对不上导致的。

4. 模型切换、Skills 和记忆：把 opencode 调校成"最懂你项目"的那一个

4.1 用 ccswitch 管理服务商，而不是反复改环境变量

很多人搜 "opencode go" 时实际想搜的是怎么把 opencode 和 ccswitch 配合起来用。先澄清一个误解：opencode 本身是 Node 工具，不需要单独装 Go 环境。你看到的那些 opencode + ccswitch 教程，核心解决的是一个真实痛点——当你有多个服务商的模型可用时，来回切换 Key 太麻烦，而 ccswitch 就是干这个的。

ccswitch 这类工具的本质是把多个服务商的 API Key 和配置集中管理，你想用哪家，就在它里面点一下"切换当前服务商"。它既可以直接影响 opencode 读取的配置，也可以在本地起一个兼容代理端口，opencode 只需要把 baseURL 指向这个本地端口即可。

所以配置链路的思路是：opencode 的配置文件里固定写一个 provider，baseURL 指向 ccswitch 的本地地址；日常使用时，你在 ccswitch 里自由选择当前生效的服务商，opencode 不用重启、不用改文件。这就把"改配置"变成了"点一下"。

经验之谈：引入 ccswitch 这类辅助工具之前，先确保你理解 opencode 本身的 provider 配置逻辑。否则一旦出问题，你很难分清是 opencode 的配置错了，还是 ccswitch 的转发问题。基础先于工具，这一条适用于所有环节。

4.2 oh-my-claudecode 和 superpowers：社区增强值不值得装

oh-my-claudecode 和 superpowers 这两个名字经常和 opencode 一起出现，但它们原本都来自 Claude Code 生态。

oh-my-claudecode 是一套社区增强脚本，给 Claude Code 加了不少便利功能，比如快捷键优化、自动接受补全、会话持久化等。因为 opencode 的目标使用场景和 Claude Code 高度重合，社区里就有人把它的一些思路移植过来。我的建议是：如果你已经很熟悉 opencode 原生操作，再来折腾这些增强；新手别一上来就装一堆脚本，否则出了问题很难判断是版本兼容还是你自己的操作问题。

superpowers 则是一套 Skills 集合，设计思路是让 AI 不要"一次性瞎猜"，而是按更结构化的流程工作——先理解需求，再列方案，再动手改，最后验证。这套思路跟 opencode 原生的 Skills 机制很搭。如果你装了 superpowers 这类 skill 包，打开 opencode 的 skills 目录看一圈，理解每个 skill 的触发方式和边界，比直接照搬效果更好。

4.3 SKILL.md 驱动的技能扩展：自己写一个 review 技能

opencode 原生支持 Skills，也就是通过一个SKILL.md文件，教 AI 在特定场景下按一套固定流程执行任务。技能的存放位置分两种：全局技能放在用户配置目录下的skills文件夹，项目级技能放在项目的.opencode/skills目录里。

我自己写过一个 code review 技能，文件放在.opencode/skills/review/SKILL.md里，内容大概是：

--- name: review description: 对当前改动做代码审查，重点找安全问题、性能隐患和逻辑漏洞 --- # Code Review Skill 当你被要求做代码审查时，按以下步骤执行： 1. 先用 git diff 查看当前未提交的改动。 2. 对每个改动文件，先看整体逻辑，再看细节实现。 3. 重点关注：用户输入是否被正确处理、资源是否释放、是否存在竞态条件。 4. 输出格式：按【严重】【建议】【疑问】三档列出问题，每条注明文件和行号。

写完保存后，在对话里让 opencode"review 一下当前改动"，它就会按 SKILL.md 里的步骤来执行，而不是凭感觉自由发挥。对于团队项目来说，这类技能文件本身也是可维护的资产，每个成员用 opencode 时都能按同一套标准来。

4.4 memory 机制：AGENTS.md 怎么让 AI 记住项目约定

opencode 在项目里维护一个叫AGENTS.md的记忆文件（早期也叫 CLAUDE 风格的项目说明）。它就像项目的"说明书"，AI 每次启动时会读取这个文件，了解项目的技术栈、目录结构、构建命令、代码规范。

我第一次真正意识到 AGENTS.md 的价值，是在接手一个 Scala 老项目时。那项目构建命令不是常见的 mvn compile，而是要先跑一个生成代码的脚本，再进 sbt shell。第一个没写 AGENTS.md 的 session，AI 连续猜错三次构建方式浪费不少 token；我在 AGENTS.md 里写清楚"构建前必须执行 generate.sh"之后，后续每次对话它都不会再犯。

AGENTS.md 可以放项目根目录让它被自动读取，也可以在全局用户配置目录放一份，写一些你个人对所有项目都通用的约定，比如"所有新增依赖必须说明用途""提交信息用英文动词开头"。项目级和全局级的记忆分开维护，互不污染。

5. TUI、VSCode 插件、IDEA 插件与桌面版：不同场景我推荐哪一套

5.1 TUI 仍然是效率天花板

opencode 最原汁原味的形态是终端里的 TUI。它不是简单的一行命令问答，而是一个完整的交互界面：左侧是会话列表，中间是对话流，右边能展示文件 diff，底部是输入框。你可以用快捷键切换会话、回滚修改、查看命令执行结果。

很多人第一次打开 TUI 会觉得信息密度太高，但我用久了反而觉得这是它最吸引人的地方。在编辑器之外单独开一个 TUI 窗口，天然隔离了"写代码"和"指挥 AI"两种心智模式。排查 bug 时，我在一个全屏终端里盯着 AI 执行命令、读日志、改文件，这种专注度是编辑器面板给不了的。

如果你只是想让它帮你改当前编辑器里打开的文件，那用插件就够了；如果你要让它独立完成一个复杂任务，比如修一个构建链路问题，建议切到 TUI。

5.2 VSCode 插件和 JetBrains IDEA 插件怎么选

VSCode 上搜 opencode 就能找到官方插件，装完之后侧边栏会多出一个 opencode 面板。它的用处在于把编辑器里的代码上下文直接传给 AI——选中一段代码，右键发给 opencode，它会基于选中内容回答，改的时候还能在编辑器里看内联 diff，点一下就能应用。

JetBrains IDEA 插件逻辑类似，对 Java、Kotlin 等 JVM 系项目的支持更顺手，毕竟 IDEA 本身对这类项目的解析能力比 VSCode 好。插件的底层还是 opencode，所以你必须先装好 CLI 才能在插件里配置路径。

我个人的分工方式是这样的：写新功能、改单元测试这类需要频繁看编辑器的场景用插件；排查复杂 bug、做全局重构、整理项目结构这类"需要 AI 独立跑很久"的场景用 TUI。插件负责连接，TUI 负责干活，两者不冲突。

5.3 桌面版的定位和适用人群

opencode 桌面版是后来推出的预览形态，很多人搜索"opencode desktop"或"opencode 桌面版"，以为它是个完整的 GUI 客户端。实际上它现在的定位更像是管理端和看板：集中查看各个会话的日志、管理模型服务商配置、实时观察 opencode 的运行状态。

对于日常敲代码的开发者来说，桌面版不是必需品，我甚至觉得它在某些场景下反而不如 TUI 顺手。但它对两类人有价值：一是团队里不太熟悉命令行的同事，桌面版能降低他们接触 opencode 的门槛；二是需要运维排障的人，桌面版的日志面板比翻终端滚动记录舒服得多。

一句话总结：命令行高手留在 TUI，编辑器重度用户留在插件，想直观管理配置和日志的用桌面版。

6. 实战：让它接手一个"看不懂"的老项目，从编译报错到前端 bug 复现

6.1 项目初始化：先给 AI 写一份"工作手册"

很多人接老项目时犯的第一个错误，就是上来就让 opencode"看一下这个项目哪里有问题"。它连项目的构建方式都不清楚，自然只能靠猜。

我的标准流程是：第一步，我会先自己快速看一眼项目结构，搞清语言、构建工具、入口文件；第二步，写一个 AGENTS.md，把技术栈、常用命令、模块结构、已知坑点列清楚；第三步，才让 opencode 开始干活。

一个 Java Maven 项目的 AGENTS.md 简化示例：

# Project: legacy-order-service ## 技术栈 - Java 17，Spring Boot 3.2，Maven 多模块 - 模块：order-core、order-web、order-job ## 常用命令 - 编译：mvn -T 1C compile - 测试：mvn -pl order-core test - 启动：mvn -pl order-web spring-boot:run ## 已知问题 - order-job 模块依赖本地私有仓库，新机器构建前需要先跑 scripts/setup-repo.sh - 测试数据库连接串在 src/test/resources/application-test.yml

这份文件不需要写得像正式文档那么详细，关键是把你作为人类已经知道但 AI 不可能知道的"项目潜规则"写进去。它花掉你十五分钟，但能省下后面数不清的无效来回。

6.2 Maven 项目里的构建闭环：从"编译不过"到 "BUILD SUCCESS"

老项目的第一个拦路虎基本都是构建。我遇到过一个情况：依赖下载报错，日志指向一个内部私有仓库的构件。第一次让 opencode 执行mvn compile，它看到报错后自行尝试改settings.xml里的镜像地址，显然不对，因为它还不了解项目依赖的是私有仓库。

正确的做法是，在 AGENTS.md 里写清楚"新机器构建前需要先跑一次 setup-repo.sh"，然后让 opencode 按指示执行。它执行命令、读取输出、根据报错改 pom 或配置、再重新编译，这个闭环才是它真正的价值所在。

操作上有两个心得。第一，给 opencode 执行构建类命令时，在配置里把超时设置得宽裕一点，Maven 首次下载依赖五分钟以上很正常，频繁打断只会让它的上下文变得碎片化。第二，遇到依赖下载失败，先区分是网络问题、私有仓库问题还是包本身的问题，不要一上来就改镜像。我见过不少 AI 把私服地址改成公共仓库，结果把项目配置搞得更乱的例子。

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

热搜里那条 "opencode playwright 怎么测试前端 bug" 是一个很实际的痛点。很多前端 bug 凭肉眼和代码审查很难复现，尤其是那种偶发性的交互问题。opencode 通过 MCP 接上 Playwright 后，可以让 AI 自己打开浏览器、操作页面、截图确认，把"我描述 bug"变成"它复现 bug"。

在 opencode.json 里加一段 MCP 配置：

{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }

然后重启 opencode，新开一个会话，给它一个明确的任务描述：

项目本地已经跑起来了，地址是 http://localhost:3000。 请用 playwright 打开页面，复现以下 bug： 点击"提交订单"按钮后，页面白屏。 复现步骤： 1. 打开首页 2. 填写用户名和手机号 3. 点击提交订单 4. 截图并检查页面 console 输出

接下来你会看到它真的去控制浏览器，一步步执行操作，然后告诉你：点击按钮后接口返回了 502，控制台有一条 CORS 报错，再结合代码定位到是某个网关的转发配置把请求路径改错了。这个链路的价值在于，AI 把"现象"和"代码"之间的距离缩到了最短，而不是像以前那样靠人去二分查找。

注意事项：第一次跑 Playwright MCP 需要下载浏览器内核，耗时可能很长；另外 MCP 串到会话里之后，模型可以控制浏览器，如果你有敏感系统千万别在共享会话里让它随便访问。

6.4 一次真实排查中的意外收获

有一次排查一个前端白屏问题，opencode 连续几轮都判断是接口返回的数据结构变了。我不想直接反驳它，而是让它去 checkpoint 一下最近的版本产出。它对比之后发现：接口结构其实一直没变，变化的是某个公共组件在数据为空时接错了一个字段名。最后修复的那一行代码，和它最初的判断完全不沾边。

这次经历让我意识到两件事。第一，AI 排查 bug 时也会被"看起来最可疑"的点带偏，所以要允许它尝试，但不能让它在没有证据的情况下反复修改代码。第二，工具链（Playwright 截图、git diff、日志）是它保持正确率的生命线，给了它这些手段，它的排查路径才真正可信。我的习惯是，凡是涉及改代码的步骤，保留明确的审批点，不让 AI 在无人确认的情况下批量改文件。

7. 这些搜索热词背后的疑问，我一次性替你回答

7.1 "opencode 套餐"到底是谁在卖

如果一个产品页面跟你说"opencode 套餐"，先分清卖的是什么。opencode 本身是开源免费的，没有任何官方套餐。所谓"套餐"，要么是模型服务商的 API 订阅（Claude、GPT 这类按量或包月的服务），要么是某些第三方平台自己包装的接入服务。

如果你看到有人卖 opencode 的"内部版本""高级套餐"，基本可以判断是割韭菜。opencode 的所有能力都在开源仓库里，模型费用只取决于你用的是哪家模型。把"工具免费"和"模型花钱"这两件事分开，很多坑就能躲掉。

第三方免费端点的情况我前面说过，hy3-free 这类名称的通道一旦下线，你只需要把 provider 配置切回官方或者本地模型即可。把配置文件里 provider 的抽象层做好，切换到新端点时就只是改几行 JSON 的事。

7.2 opencode、codex、claude code、pi：到底哪个 agent 好用

这是热搜里对比最多的一组。我直接给一张表，列出我实测下来的感受：

我的结论是：如果你只想在 Claude 生态里获得最顺畅的体验，Claude Code 依然是第一选择，毕竟原生整合度无法替代；如果你想自由切换模型、接本地模型、不被订阅绑死，opencode 更合适；Codex 的特点是自动化倾向强，适合“给它一个任务让它在分支上把活全干完”的场景；其他新兴终端 Agent 各有亮点，但生态和社区积累短期内很难和前面几个比。

再说句实在话，工具选型不要只看功能表。opencode 最打动我的不是它能写多少行代码，而是它把"换模型"这件事变成随时可做的操作。今天试这个模型，明天换那个端点，配置文件一改就完事，这种不被绑架的自由感，用过的人自然懂。

7.3 unexpected server error 的日志排查法

排查顺序固定是这样的：先看错误发生在哪个阶段，再取日志，最后做对照实验。

opencode 报unexpected server error时，很多人第一反应是重装，这是最浪费时间的做法。先找到日志文件，位置一般在：

• macOS / Linux：~/.local/share/opencode/log/
• Windows：%LOCALAPPDATA%\opencode\log

如果找不到，执行opencode --print-logs或者看桌面版的日志面板。日志里如果能看到 HTTP 状态码，判断就很直接：401 通常是 Key 失效或没传对；403 大概率是服务商风控，检查账号是否正常；429 是限流，等一下再试；5xx 和超时则是服务端问题，优先怀疑第三方端点或网络链路。

定位根因最快的方式是做对照实验：把 provider 切回官方默认端点，用同一个问题再问一次。如果官方端点正常，那问题就锁定在自定义配置上；如果官方端点也报错，再检查 opencode 版本和日志输出。

7.4 我的最终使用建议

折腾 opencode 这段时间，我的常用组合是：日常主力项目用官方模型 Key 加上一个稳定的opencode.json，实验性需求走 Ollama 本地模型，多个服务商之间用 ccswitch 管理切换。Skills 按需加，绝不一上来就装一大堆；AGENTS.md 每个项目都写，但内容保持精简，只放真正影响 AI 行为的关键信息。

版本升级方面，我现在的策略是在一个测试项目里先升，跑几天确认没问题再应用到主力项目。opencode 迭代很快，新功能很香，但稳定性和兼容性永远比新功能重要。最后再提一句我一直以来的习惯：无论工具多强大，最终对代码质量负责的还是你自己——让 opencode 放手去跑，但保留关键步骤的确认权。