企业官网建设流程全解析

开源终端Agent opencode：从安装、模型接入到Skills排障的完整实操记录

第一次注意到 opencode，是看到有人在群里说“Charm 也做 AI 编程工具了”。Charm 就是做 gum、glow、BubbleTea 那一票漂亮终端工具的工作室，他们做的终端 UI 一直很对我的审美。当时我正被项目里好几个模型 API 折腾得焦头烂额，Claude Code 好用但绑死 Anthropic 的 key，Codex 又只能在 OpenAI 生态里打转。所以当知道 opencode 是一个开源、模型自由、终端优先的 AI 编码 Agent 时，我几乎没犹豫就装上试了。

这篇东西不是官方文档的复述，是我自己从 Windows、macOS 两台机器上踩过来的实操记录。内容包括 opencode 到底是什么来头，怎么安装、怎么配置免费模型，怎么理解“opencode go”和 CC Switch 的关系，怎么把 Skills、Superpowers、Memory 这些社区玩法全部接到自己的工程里，也包括 VSCode、IDEA 插件、桌面版，甚至用 Playwright 修前端 bug 的真实流程。最后一部分是排错——我几乎把所有能踩的坑都踩了一遍，包括 Windows 那个“无法将 opencode 识别为 cmdlet”的报错，和 dreaded 的 unexpected server error。

1. 一个Go写的终端Agent，为什么值得从Claude Code换过来

1.1 opencode是哪个团队做的，底层为什么用Go

先说结论：opencode 是 Charm 公司（charmbracelet）发起的开源项目，GitHub 仓库在 charmbracelet/opencode 下。Charm 这家公司在开发者圈子里不算陌生，做过 Glow（终端 Markdown 阅读器）、Gum（Shell 脚本美化工具）、VHS（终端录屏 GIF 工具），还有最出名的 BubbleTea——一个 Go 写的 TUI 框架。所以 opencode 一出生就带了很强的 Charm 基因：终端界面特别跟手，启动快，交互流畅。

我之前一直以为这类 AI 编码 Agent 应该是 Node 写的，毕竟 Claude Code、Codex 的 CLI 都跑在 Node 运行时上。opencode 直接用 Go 编译成单二进制，好处非常实际：没有 Node 版本冲突，没有 node_modules 地狱，装完就是一个文件，放到 PATH 里就能跑。对我这种机器上同时有多个 Node 版本的人来说，这体验简直是降维打击。社区里说的“opencode go”，有一部分含义就是指它的 Go 底层实现——速度确实是肉眼可见的快，冷启动基本感觉不到等待。

1.2 和 Claude Code、Codex、Pi 放在一起怎么选

很多人搜“opencode codex claude code”、“opencode codex pi 哪个 agent 好用”，说明大家真正纠结的是：终端 AI 编程 Agent 这么多，到底选哪个。我贴一张我自己整理的对比表，按我实际用下来的体感写，不是参数背诵：

我的选择逻辑很简单：如果我手上只有一两个 API key，哪个工具都不重要；但如果你像我一样，今天用 Gemini 的免费额度跑普通任务，明天切 Claude 处理复杂重构，后天可能还要用本地 Qwen 兜底，那 opencode 的“模型自由”就是刚需。它不是某个模型的专属客户端，而是一个“把模型调度和编辑器整合好的 Agent 壳”。

另外，开源带来的可审计性是很多人忽略的。项目里跑着能动文件、能执行命令的 Agent，如果你连它代码都看不到，心里多少会有点不踏实。opencode 开源后，权限控制写在哪、命令执行逻辑是什么、上下文怎么上传的，这些都能自己查，也能在 issue 里提意见。对我这种要给客户交付代码的人，这一点是决定性的。

2. 从零到一：安装、opencode go 与 CC Switch 搭桥

2.1 安装 opencode 的几种姿势

opencode 的安装方式在官网 opencode.ai 上写着，最常用的是那个一键脚本：

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

macOS 和 Linux 上这个脚本基本不会出问题，装完会自动把可执行文件放到/usr/local/bin或~/.local/bin。Windows 上强烈建议别用 WSL 绕路，直接用 Scoop 或 WinGet 装：

# Scoop scoop install opencode # WinGet winget install opencode

如果你喜欢用 Homebrew，Mac 上也可以brew install opencode。装完先验证一下版本：

opencode --version

我第一次在 Mac 上跑这个命令，看到版本号出来后，心里就知道这工具稳了——因为安装过程没有任何多余输出，干净利落。

2.2 Windows 报错“无法将 opencode 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”

这个报错绝对是 opencode 搜索热词里最惨烈的一个，因为它直接把一大票 Windows 用户卡在第一步。我在 Windows 11 的干净环境里复现过这个错误，结论很简单：安装脚本把 opencode 写进了某个目录，但这个目录不在你的 PATH 环境变量里。WinGet 装的路径一般在%LOCALAPPDATA%\Microsoft\WinGet\Links，Scoop 装的则在自己那个 shims 目录。

排查链路我放在后面排错章节里完整写，这里先给一个最快解决方案。装完之后手动检查一下：

where.exe opencode

如果提示找不到，就把 opencode 所在目录加到用户 PATH 里。注意加完后一定要重新开一个终端，因为 PowerShell 不会自动刷新环境变量。这个“重开终端”的动作，至少能解决掉一半人的问题。

2.3 “opencode go”到底在说哪件事

搜索词里“opencode go”出现了很多次，还和“需要配合 cc switch 等工具”绑定在一起。我猜大家是怎么理解的呢？两种：一是把它当成“开工命令”——就像敲code .打开 VSCode 一样，幻想敲opencode go就能直接启动编码会话；二是指 opencode 的 Go 语言实现需要依赖 cc switch 之类的工具切换模型供应商。

先说第一种。opencode 的启动命令就是opencode本身，没有所谓的opencode go子命令。跑起来之后在对话框里描述你的任务，Agent 就会开始读代码、执行命令、改文件。很多中文教程把“配置完模型之后输入 opencode 开始干活”简写成了“opencode go”，于是这个词就流传开了。你真正要做的是确保 shell 里能敲出opencode，然后敲下去，仅此而已。

再说第二种。opencode 支持多个模型供应商，但你在系统环境变量里同时配置好几个 key 的时候，管理就会变得很乱。这时候很多社区用户会引入 CC Switch 这类 GUI 工具，用来在 Claude Code、Codex、opencode 之间一键切换不同的 API 供应商配置。我的实际用法是：在 CC Switch 里为 opencode 单独建一套环境变量配置（比如当我切到“Gemini 工作流”时，就导出ANTHROPIC_BASE_URL到 Gemini 代理、OPENAI_API_KEY留空之类），然后用它一键加载对应模型供应商的配置。opencode 本身不依赖 CC Switch，但它确实是你同时玩多个 Agent 和多个模型时非常好用的“搭桥工具”。

2.4 配置文件放在哪里，长什么样

opencode 的配置路径在~/.config/opencode/opencode.json（macOS 和 Linux），Windows 在%USERPROFILE%\.config\opencode\opencode.json。第一次运行 opencode 会在目录下自动生成配置文件。我在里面定义的几个关键字段：

{ "$schema": "https://opencode.ai/config.json", "model": "anthropic/claude-sonnet-4", "provider": { "openai": { "api_key": "env:OPENAI_API_KEY", "base_url": "https://api.openai.com/v1" }, "ollama": { "base_url": "http://localhost:11434/v1" } }, "skills": true, "permission": { "read": "allow", "edit": "ask", "bash": "ask" } }

这里解释一下关键设计。model字段指定默认模型，provider配置不同供应商的 key 和地址。skills开启技能系统，具体后面细说。permission是权限控制：我让 opencode 直接读文件不需要问我，但修改文件和执行 shell 命令必须经过我确认。这个配置习惯帮我避免过很多次“Agent 突然自作主张把代码改了”的尴尬。

3. 模型接入、套餐与“免费模型”的真实成色

3.1 opencode 有套餐吗？免费吗？

先说清楚一个容易搞混的概念：opencode 本身是免费开源的，它不内置模型额度，也不会因为你多用几次就弹出付费墙。你搜“opencode 套餐”时看到的结果，绝大多数要么是第三方聚合 API 的付费计划，要么是模型厂商自己的订阅。

也就是说，你只需要为模型 API 付费。Claude 的 key 走 Anthropic 官方计费，GPT 走 OpenAI 计费，Gemini 走 Google 计费。opencode 作为一个开源工具，赚不到你的模型钱。如果你用的是本地模型，比如 Ollama 跑的量化版 Qwen，那连 API 费都不用花，只需要电费。对我这种每天都在用 AI 写代码的人来说，这反而是最省钱的方案：谁家模型搞活动用谁家，切换成本几乎为零。

3.2 免费模型到底能不能用，怎么配

搜索热词里“opencode 免费模型”热度很高。我自己试过的免费策略有这么几种：

1. Google Gemini API 免费额度：注册 Google AI Studio 后能拿到一个有限 RPM 的免费 key，日常做代码解释、写测试、重构这种轻量任务完全够用。在 opencode 里把模型配成 Google Gemini 即可。
2. OpenRouter 上的:free系列模型：OpenRouter 平台有很多免费模型，配置时模型名填vendor/model:free，比如deepseek/deepseek-chat:free。速度看时段，不稳定的时候会排队。
3. 本地 Ollama：完全离线，数据不外发，适合处理敏感项目。质量取决于你机器能跑多大的模型，我自己笔电上跑qwen2.5-coder:14b，写单测和简单重构够用。
4. 一些社区共享的“免费通道”：也就是大家说的 hy3-free 之类。我直说，这类通道我试过两三次就放弃了，问题很多。你搜“opencode hy3-free 下线了吗”，我想说它挂不挂都正常，因为这类通道通常是小团队或个人用闲置卡开的，限流、密钥轮换、超负载是常有的事。

配置免费模型时，以 OpenRouter 为例：

{ "model": "deepseek/deepseek-chat:free", "provider": { "openrouter": { "api_key": "env:OPENROUTER_API_KEY", "base_url": "https://openrouter.ai/api/v1" } } }

然后启动 opencode 看模型能不能正常响应。如果模型列表里没有你想要的，先确认拼写和厂商前缀对不对。我的经验是：免费模型适合拿来跑量，不适合跑复杂重构。你让它帮你改 50 个文件的大型重构，免费模型很容易跑崩或产生低级错误，到时候花在审查上的时间不比对着一块一块改更少。

3.3 Java/Maven 工程师最关心的“opencode mvn 配置”

“opencode mvn”这个搜索词我怀疑是 Java 开发者发出来的。要说明的是：opencode 没有 mvn 子命令，它不是 Maven 插件，也不是构建工具。你在 Maven 项目里用 opencode，重点从来不是“配置 mvn 本身”，而是怎么让 opencode 理解 Maven 项目的结构和构建方式。

我自己的习惯是在项目根目录先给 opencode 一条这样的指令：

先读取 pom.xml 和 src/main/java 下的包结构， 告诉我这个项目的模块划分、Java 版本、关键依赖， 然后帮我找出 main 方法的入口。

opencode 读取文件的能力很强，你只要允许它读文件，它很快就能把 Maven 项目的骨架理解个大概。真正会出问题的是 opencode 执行mvn命令的权限，因为构建耗时长、输出量大，容易把 Agent 的上下文搞得很臃肿。我的做法是在权限配置里把mvn test、mvn compile这类命令设为可执行但需要确认，避免它一发不可收拾地狂跑测试。

另外，如果你在 JetBrains IDEA 里用 opencode，插件会把当前项目上下文传给 CLI，Maven 项目的依赖树信息也会被读取，这时候你问它“这几个类为什么编译不过”，它会结合 IDEA 的报错信息给出比较靠谱的答案。我后面专门写 IDEA 插件的用法。

3.4 为什么我建议你留一个本地模型兜底

有一次我正赶一个上线前的 bug 修复，Anthropic 那边突然限流，API 一直返回 429。当时离 Deadline 就两小时，我人直接麻了。后来我养成了在配置里加一个 ollama provider 的习惯，遇到主模型挂掉或者网络不稳，直接在 opencode 里Ctrl+L切模型，用本地 Qwen 顶上去继续改。速度肯定比云端慢一点，但至少不会中断。

配置方式就是上面 JSON 里的 ollama provider。前提是你已经在本机装好 Ollama 并拉了一个模型，比如：

ollama pull qwen2.5-coder:14b

然后在 opencode 里通过模型选择切到ollama/qwen2.5-coder:14b就行。这个兜底方案我强烈建议所有把 opencode 当日常生产力工具的人都配一个，费用为零，关键时刻救命。

4. 真正把 opencode 用起来：Skills、Superpowers、Memory 与一套标准使用流程

4.1 opencode Skills 是什么，怎么加？

Skills 是近几年 AI 编码 Agent 生态里最火的概念之一，大致意思就是给 Agent 准备一批“带说明书的专用工具”。opencode 也支持 Skills，社区里很多人搜“opencode skills”或者把 oh-my-claudecode 的东西往 opencode 上迁移，就是在搞这个。

opencode 的 Skills 本质上是一组带SKILL.md说明文件的目录。你可以在项目里建.opencode/skills目录，也可以放到全局配置目录。我的做法是建一个全局 skills 目录，里面放写单测、代码审查、Git 提交信息生成这类通用技能。给个最直观的例子：我写了一个“生成单元测试”的 skill，目录结构如下：

~/.config/opencode/skills/ generate-ut/ SKILL.md templates/ junit5-test.tpl

SKILL.md里写清楚这个 skill 的触发条件、执行步骤和模板位置。opencode 启动时会加载这些技能描述，当任务匹配到时，它会优先按 SKILL.md 的流程走。这个机制让我省了很多重复啰嗦的提示词——以前我每次都要写“请按照项目惯例，用 JUnit 5 写测试，覆盖正常流程、边界条件……”现在一个@generate-ut引用就搞定了。

4.2 把 Superpowers 装进 opencode

社区里“opencode 安装 superpowers”的呼声也很高。Superpowers 最初是给 Claude Code 用的一套增强技能集，作者是知名插件开发者 Jesse Vincent（也就是 obra）。里面包含了很多高质量的工作流技巧，比如“如何拆解大型任务”“如何做代码评审”。这套技能并不是 Claude Code 专属，很多内容可以迁移到 opencode 里用。

我的迁移步骤很简单：

# 先克隆 Superpowers 仓库 git clone https://github.com/obra/superpowers.git ~/superpowers

然后看仓库里的skills目录，里面每个子目录对应一个技能。把这些技能目录软链到 opencode 的 skills 目录里：

mkdir -p ~/.config/opencode/skills ln -s ~/superpowers/skills/* ~/.config/opencode/skills/

重启 opencode 后，你可以在提示里让 Agent 加载其中一个技能，比如让它“用 brainstorming 技能帮我把这个功能的实现方案拆成步骤”。不过要提醒一句：Superpowers 是为 Claude Code 设计的，里面个别 prompt 写法在 opencode 上不一定会 100% 生效，需要自己微调。社区里也有人在做专门适配 opencode 的 fork，搜索“oh-my-claudecode”相关仓库时能看到不少适配脚本，但注意鉴别质量。

4.3 Memory：让 Agent 记住你们团队的习惯

“opencode memory”这个关键词搜索量也不小。我自己用下来的理解，opencode 的 Memory 机制更像是一个“可持久化的项目笔记”：你让 Agent 记住的东西会被写入一个 Memory 文件，在后续会话中自动加载。这就避免了每次开新会话都要重新交代一遍背景的麻烦。

具体做法是：在项目根目录放一个MEMORY.md，里面记录项目的技术栈、目录结构、编码规范、常用命令。比如这样：

# 项目记忆 - 项目基于 Spring Boot 3.2，Java 21，Maven 管理依赖 - API 路由统一前缀 /api/v1 - 修改数据库表后必须同步更新 liquibase changelog - 跑单测用：mvn test -Dtest=xxxTest

opencode 在会话开始时读到这个文件，就能对你的项目有初步认知。我在实际项目中，还会在让 Agent 做完一次大重构后，叫它把本次变更的关键信息追加到 MEMORY.md 里。这样做的好处是，下次另一个会话接手这个项目时，Agent 不至于一头雾水。团队协作时，这个文件也可以提交到 Git 仓库里共享，等于把你的工程经验沉淀到了项目本身。

4.4 一套可以直接照搬的标准使用流程

搜索词里“opencode 标准使用指南”说明很多人需要的是一个稳定可复用的使用套路。我把自己现在的日常流程分享出来，有需要的直接复制：

第一步：项目初始化。进到项目目录，第一次运行 opencode，先让它扫描项目结构和关键配置文件。我会敲：

请先阅读项目的 README、包结构和构建配置， 然后把项目技术栈、启动方式、测试命令整理成 MEMORY.md。

这一步做好，后面所有任务它都带着项目背景。

第二步：小步快跑。Agent 不是你一次性把需求说完它就能完美交付的。我的习惯是先给它一个小任务，比如“帮我把AuthService里的登录逻辑抽出一个LoginStrategy接口”，让它完成后再审查改动。跑通一个小目标，再继续下一个，而不是让它一口气改完十个文件。

第三步：全流程审查。opencode 改完代码后，我会让它生成 diff 摘要，然后我自己打开 Git 对比工具逐行看。记住一句话：Agent 写代码，你审代码。任何 AI 编码工具都不应该直接绕过 code review。

第四步：沉淀。如果这次任务行得通，我会把其中的技巧或流程写进 MEMORY.md 或一个 skill，下次遇到类似问题直接引用。这套“初始化-小步-审查-沉淀”的循环，比任何花哨配置都重要。

5. 接到编辑器里：VSCode、IDEA、桌面版、接手老项目和 Playwright 修前端 bug

5.1 VSCode 插件：最轻量的接入方式

opencode 官方提供了 VSCode 扩展，在扩展市场搜“opencode”就能找到。插件的核心作用是在 VSCode 侧边栏嵌一个 opencode 面板，方便你边看代码边和 Agent 对话，不用切终端。

装完后你需要确保 opencode 的 CLI 已经在 PATH 里，插件默认会绑定当前项目目录作为上下文。我最常用的场景是：在编辑器里选中一段代码，右键选择“发送给 opencode”，然后让它解释这段逻辑或者生成对应测试。这对快速理解陌生代码非常有帮助。

插件有一个小坑：如果你改了全局配置或 skills，插件侧可能不会自动刷新，需要重载窗口（Command Palette 里执行 “Developer: Reload Window”）才能生效。如果你发现插件里的 opencode 行为和终端里不一致，先重载窗口再说。

5.2 JetBrains IDEA 插件：Java 项目的正确姿势

IDEA 的 opencode 插件同样是搜索热词，大概是因为 Java 开发者习惯了在 IDEA 里完成所有事情。JetBrains 插件装好后，会在右侧工具窗口出现一个 opencode 面板。

我在 IDEA 里的工作流一般是：先点开面板，让 Agent 读取项目的 Maven 依赖树；然后针对某个报错类，让 Agent 分析 stack trace 并给出修复建议；最后它改完代码，我直接跑mvn test验证。因为 IDEA 已经加载了项目模型，所以 Agent 可以拿到更准确的类路径和符号信息，比在终端里凭文本猜项目结构要准得多。

IDEA 插件同样要求本机装 CLI。我在 IDEA 里遇到过一个很典型的问题：插件运行时报错说找不到 opencode，但终端里明明可以。原因还是 PATH——IDEA 在 macOS 上可能不会加载 shell 的 PATH，需要用launchctl setenv PATH $PATH这类方式把 PATH 注入 GUI 环境，或者在插件设置里手动指定 opencode 可执行文件路径。

5.3 桌面版适合谁

搜索词“opencode 桌面版”说明有人对终端界面不感冒，更想要一个独立 App。opencode 也确实提供了桌面端，适合那些主要在图形界面里工作、又不想开 IDE 的人。

我自己对桌面版的评价是：可用，但不如终端和 IDE 顺手。终端版有快捷键、有脚本化能力，IDE 版有项目上下文，桌面版夹在中间，优势主要是“专注”和“好看”——它给你一个独立的对话窗口，减少上下文切换。如果你只是想让 AI 处理一些零散任务，比如“写段正则”或“翻译报错信息”，桌面版够用了；但真正干大活，我还是建议回到项目目录下的终端或 IDE 面板。

5.4 用 opencode 接手一个遗留项目

“opencode 接手开发项目”这个搜索词特别对我胃口，因为我频繁干这种事。接手老项目最痛苦的不是写代码，而是理解别人的思路、找到入口、摸清隐藏的约定。opencode 在这方面意外地好用。

我的接手流程是这样的。首先用 /init 或手动让 Agent 扫描项目结构，生成架构笔记。接着问它三个问题：

1. 这个项目的核心业务流程是什么？
2. 主要的技术栈和第三方依赖有哪些？
3. 项目怎么启动，怎么跑测试，有没有特殊的环境要求？

等它回答完，我会把自己的理解和文档对照一遍，发现不一致的地方再让它深挖。这样基于 Agent 的信息，我对项目的掌控速度会快非常多。实际接手一个 Spring Cloud 微服务项目时，我靠这个流程在半天内理清了六个服务之间的调用关系，而按照以前纯靠读代码的进度，至少需要两天。

接手项目时特别适合使用 Memory 机制。我会让 Agent 把扫描结果写进 MEMORY.md，这样后续每次会话它都记得服务模块的划分和调用关系，不会重复问你“这个服务是干什么的”。

5.5 让 opencode 用 Playwright 定位并修复前端 bug

这个场景我第一次玩的时候挺震撼。那是一个 React 页面在特定浏览器宽度下布局错乱的问题，肉眼调试很费劲。我直接对 opencode 说：

用 Playwright 写一个脚本，在 375px 宽度下打开当前项目的前端页面， 截屏并输出页面元素的 bounding box。

opencode 会自己安装/调用 Playwright，写测试脚本，启动本地前端服务，然后截图。我把运行输出和截图反馈给它，让它分析哪个元素超出了容器。它定位到是 Flex 布局里某个min-width: 0没有设置，导致子元素撑破了父容器。整个排查过程，它做了我过去至少一个小时的工作。

这个场景的价值在于：Agent 可以操作浏览器，就等于把“验证”也自动化了。它不再只是猜代码，而是真的去跑、去看、去对比。结合 Playwright，opencode 能做的不只是修 bug，还包括：写端到端回归测试、抓取页面性能指标、模拟用户点击路径等。我对前端同学的建议是，把“让 Agent 写 Playwright 复现脚本”当作排查 bug 的第一步，往往比人肉反复刷新要高效得多。

6. 实测过程中最常踩的坑与排查路径

6.1 Windows cmdlet 报错的完整排查链路

回到那个高频问题。如果你在 PowerShell 里执行opencode得到“无法将 opencode 项识别为 cmdlet……”的报错，按下面顺序排查，基本都能解决：

第一步：确认安装位置。用Get-Command opencode -ErrorAction SilentlyContinue看系统能不能找到。如果没有任何输出，说明 opencode 压根没被找到。

第二步：检查 PATH。打开“系统属性 -> 环境变量”，看用户 PATH 或系统 PATH 里有没有 opencode 的安装目录。WinGet 装的 Links 目录和 Scoop 的 shims 目录是最常见的两个位置。如果不在，手动加进去。

第三步：重新打开终端。PowerShell 不会自动刷新 PATH，一定要新开一个窗口再试。这一步能解决 50% 的“明明加了 PATH 还是没用”问题。

第四步：直接调用完整路径。如果只是想临时验证安装是否成功，可以跳过 PATH，直接执行完整的 exe 路径。WinGet 安装的一般能通过where.exe查到推荐路径，或者用Get-ChildItem -Path $env:LOCALAPPDATA -Filter opencode.exe -Recurse -ErrorAction SilentlyContinue找到它。

这个报错本质上不是 opencode 的问题，而是 Windows 环境变量管理的经典坑。它一点也不难解决，只是第一次遇到时会让人心态爆炸。

6.2 error: unexpected server error. check server logs

“opencode error: unexpected server error. check server lo……”这个报错是很多人搜索的另一个重灾区。我遇到这个报错时，第一反应不是查 opencode 的日志，而是先看模型 API 是否正常。

这个报错绝大多数情况下是上游模型 API 返回了异常，opencode 只是把错误转包给了你。排查路径：

1. 打开 opencode 的日志。终端跑 opencode 时，日志默认在~/.local/share/opencode/log或/tmp/opencode-log-*，具体位置输出版本信息能看到。
2. 打开日志，搜索堆栈里的 HTTP 状态码。如果是 401/403，说明 API key 无效或没有对应模型的权限；如果是 429，说明限流；如果是 5xx，说明模型服务商那边挂了。
3. 在配置文件里临时把模型切换成同一个供应商的另一个模型，或者切成本地 Ollama，确认问题是否复现。如果本地模型能跑通，说明问题出在远端 API，而不是 opencode 本身。

有一次我开了半天“unexpected server error”，最后发现是我改了环境变量但没重新加载，导致 opencode 拿到的API_KEY是空的。这种低级错误，在检查完 key 和日志之前永远想不到。

6.3 模型“答非所问”或无视系统提示怎么办

当你发现 opencode 开始无视你写在配置文件里的指令或者老是记不住项目上下文时，第一反应应该是：上下文是不是被污染了。

AI 编码 Agent 的上下文窗口是有限的，当项目文件太多、日志太长、对话历史太碎时，后面的指令效果会衰减。我的止血操作是：

• 用/compact类指令压缩历史，或者直接开新会话；
• 把项目的关键信息固化进 MEMORY.md，而不是靠对话里反复强调；
• 检查当前会话模型是否被切成了免费的弱模型——我有一次切到免费模型忘了切回来，结果 Agent 各种犯低级错误，我还以为是配置问题。

还有一个常见的坑：项目目录里的.gitignore没生效，opencode 会把node_modules、target这类巨大目录也读进上下文，导致上下文窗口迅速爆炸。配置里确认一下忽略规则，必要时独立维护一份 opencode 的忽略清单，别让它去读那些没用的依赖目录。

6.4 两个值得养成的止损习惯

最后说两个我在大量使用 opencode 后总结的习惯。

第一，不要在默认配置下把命令执行权限全放开。我见过有人图省事把bash权限设成 allow，结果 Agent 在没有确认的情况下跑了危险的清理命令。我的建议是：读文件可以 allow，写文件和执行命令必须 ask。多一次确认不会拖慢太多进度，却能拦住 90% 的意外。

第二，随时准备切换模型。把本地模型兜底配好，把 CC Switch 的环境变量搭好，一旦主模型异常能在 30 秒内切走，而不是卡在那里干等。我把这个流程称做“开工前的 5 分钟准备”：检查 API key 额度、确认默认模型、搭好兜底通道。准备工作越充分，后面出岔子的概率越低。

写在最后

如果你问我 opencode 最打动我的点是什么，我会说：它把“模型自由、终端体验、可扩展性”这三件事同时做好了。以前我用 Claude Code 时总觉得被绑死在一个生态里，用 Codex 又觉得交互不够顺手，opencode 让我真正体会到“工具是工具、模型是模型”的分离感。现在它已经是我日常处理代码事务的主入口了——从写测试、改 bug，到用 Playwright 复现前端问题，再到接手陌生项目，我都是先让 opencode 读一遍上下文，再和它分工协作。

根据我踩过的那些坑，最后再分享一个小技巧：opencode 这个工具迭代非常快，如果你发现某个配置选项不起作用、某个功能找不到，优先去官方 GitHub release 页面看 changelog，很多问题其实是新版本改了用法，不是你配置错了。保持每周更新一次的习惯，让它始终跑在新版本上，你会少踩很多鬼知道是什么的坑。