企业官网建设流程全解析

我这阵子把 opencode 完完整整摸了一遍。从安装、模型配置、接老项目，到用 Playwright 让它自己复现前端 bug，再到 VS Code、JetBrains 插件和桌面版全试了一圈。这篇文章不聊虚的，就是一份基于实际体验的 opencode 使用手记，把安装、配置、玩法、踩坑一次性讲透。无论你是刚听说这个名字，还是已经装上但一运行就报错，都能在这里找到对应的解法。

先说清楚文章适合谁看。如果你平时用 Copilot 这类补全工具，但对“让 AI 直接读仓库、改代码、跑命令”这件事持怀疑态度，那 opencode 值得你花半小时试一下。如果你的电脑上已经装了 opencode，但总卡在模型选择、报错、配置不生效这些细节上，这篇文章的排查部分能帮你省不少时间。

1. 先搞清楚 opencode 是什么，以及为什么大家都在聊它

1.1 它既不是补全插件，也不是简单的聊天框

很多人第一次听说 opencode，会下意识以为它又是一个 IDE 里的自动补全插件，或者像网页版 ChatGPT 那种问答框。实际上完全不是一回事。

opencode 是一个运行在终端里的开源 AI 编程 Agent，当前由做 Serverless Stack（SST）的那批核心开发者主导。它的定位很直接：给你一个“能理解整个项目”的 AI 协作者，而不只是“看几行代码给你提建议”的工具。你可以直接对它说“帮我查一下这个登录接口为什么返回 401”，它会自己去翻代码、找路由、看日志，定位到具体文件，然后提出修改方案，甚至直接改完让你 review。

这个过程和我们平时用聊天框最大的区别在于上下文。聊天框只能靠你复制粘贴片段，opencode 则启动时就加载了整个项目的结构、Git 状态、文件索引，配合 LSP（Language Server Protocol，语言服务器协议）能看懂类型、引用关系、报错位置。你问它问题，它不是在猜，而是在“查”。

打个比方：Copilot 类工具像输入法，你打字它预测词；opencode 更像一个刚入职、但读代码速度极快的临时工程师，你给它一个任务，它能自己去翻资料、动代码、跑测试，然后把结果拿给你确认。

1.2 和 Claude Code、Codex 放在一起比，差距和优势都在哪

现在提到 AI 编程 Agent，绕不开 Claude Code、OpenAI Codex 这几个名字。opencode 和它们同属一个赛道，但有几个非常明显的差异点。

第一是开源和社区驱动。opencode 的整个代码库是开放的，你可以看到它内部怎么处理上下文、怎么调度模型调用，也可以自己提交代码、改行为逻辑。对于喜欢折腾、想把工具调成自己形状的开发者来说，这是很核心的吸引力。相比之下，Claude Code 和 Codex 更像是“官方定义的盒子”，你能配置的选项相对有限。

第二是模型无关。opencode 在设计上不绑定任何一家模型厂商。你可以接 Anthropic 的 Claude、OpenAI 的 GPT、Google 的 Gemini，也可以接本地跑的 Ollama、LM Studio，甚至各家提供免费额度的模型服务。这意味着你不会被某一家的价格、限流或地区可用性绑架。这也是我在团队里推荐它的重要原因：大家用的模型可以不一样，但 Agent 框架是统一的。

第三是生态扩展能力。opencode 有一套 Skills 技能包机制，可以把你反复使用的操作流程沉淀成可复用的“技能”，下次一句话就能调用。它还支持 Memory 记忆机制，让 Agent 记住项目偏好和你的编码风格。插件生态里，VS Code 插件、JetBrains IDEA 插件、桌面版都已经有人在用，覆盖了终端之外的使用场景。

当然它也有不完美的地方。官方文档更新速度赶不上功能迭代，有些新特性要在 GitHub 的 issue 和讨论区里才看得到。另外，因为模型是自由接的，效果上限很大程度取决于你选了哪个模型、怎么配的参数。同样一个任务，有人用起来像神兵利器，有人用起来像人工智障，差异往往出在模型选择和上下文管理上。

1.3 谁更适合用它：从新手到老手的使用场景

我用了这段时间，总结出三类人最适合上手 opencode。

第一类是经常接手别人代码的人。打开一个陌生仓库，第一反应都是“这项目到底怎么跑起来的”。opencode 能快速给你梳理项目结构、入口文件、依赖关系，甚至帮你写好本地启动步骤，省去一页页翻文档的时间。

第二类是写前端页面、需要频繁调整交互和样式的开发者。配合 Playwright，你可以让 opencode 自己打开浏览器、操作页面、复现 bug，这比我以前“截图 + 文字描述”的沟通方式高效得多。

第三类是愿意花点时间配置工具、追求长期效率的人。opencode 的可玩性很高，Skills、Memory、LSP、模型路由这些机制一旦配好，后续每个项目都能复用。它不是一个开箱即用到 100 分的工具，但上限确实高。

如果你是从来没碰过终端 AI Agent 的纯新手，我也建议装一个试试。不用一上来就搞复杂配置，先选个便宜的模型，让它帮你写个脚本、改个小 bug，感受一下“对话式编程”到底顺不顺手，再做深度投入。

2. 安装 opencode：不同平台的路子和我踩过的坑

2.1 三步搞定安装：各平台安装方式一览

opencode 的安装方式不少，覆盖 macOS、Linux、Windows，还有一个 npm 全局包。我按平台列一下当前主流的方法，你可以根据自己的环境挑。

macOS 上，用过 Homebrew 的话一条命令搞定：

brew install opencode

Linux 和 macOS 通用，也可以用官方提供的安装脚本：

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

Windows 上，如果你是 Node 环境，最省事的方式是用 npm：

npm install -g opencode-ai

装完验证一下，终端执行：

opencode --version

能看到版本号就说明装好了。除了这些，官方还提供 GitHub Releases 里的二进制包，以及 Docker 镜像，适合服务器环境或不想污染本机全局环境的情况。我的建议是：本机开发首选包管理器安装，服务器上用二进制或 Docker，干净好维护。

还有一个小细节：opencode 也提供桌面版，和终端版共用一套配置，适合不习惯终端操作的人。但核心功能都在终端版里，桌面版目前更像一个带界面的入口，装上不亏，但别指望它比 CLI 多出什么额外能力。

2.2 高频报错：“无法将 opencode 识别为 cmdlet”到底怎么破

Windows 用户最容易遇到的热词之一就是这个报错：

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

我第一次在 Windows 上装的时候也碰到了。这个报错的本质是 PATH 里没有包含 npm 全局包的安装目录，或者当前 PowerShell 会话没有刷新环境变量。大部分情况下不是 opencode 没装上，而是系统找不到这个命令。

排查和解决一般分三步。

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

npm prefix -g

输出结果通常是一个路径，比如C:\Users\你的用户名\AppData\Roaming\npm。接下来确认这个目录在系统 PATH 里。在 PowerShell 执行：

[Environment]::GetEnvironmentVariable("Path", "User")

如果输出里没有刚查到的 npm 全局目录，那就手动把它加进去。图形界面路径是：系统属性 -> 环境变量 -> 选中用户变量中的 Path -> 编辑 -> 新建 -> 粘贴路径。

第二步，如果 PATH 里有，但当前终端还是不认识，那就关闭当前 PowerShell 窗口重新打开一个。新开的窗口会重新加载环境变量，一般就能识别了。

第三步，做完上面两步还是报错，检查 Node 是否正常。opencode 的部分安装方式依赖 Node 运行，你可以执行node -v和npm -v确认。如果 Node 本身没问题，再试一下重新安装：

npm uninstall -g opencode-ai npm install -g opencode-ai

这里多提醒一句：在 Windows 上用终端类工具，建议直接用 Windows Terminal，别用老旧的 cmd 或者 Windows PowerShell 5.1。后者在某些环境下会出现脚本执行策略限制，导致运行不了命令。如果遇到和“脚本执行策略”相关的报错，可以在 PowerShell 里执行Get-ExecutionPolicy查看当前策略，再根据自己机器的安全要求调整。

提示：千万不要图省事把执行策略改成完全不受限。更好的做法是只对当前用户放开，或者用管理员身份执行需要的操作，改完再恢复原策略，安全第一。

2.3 装好后先别急，把这几项环境检查做了

很多人装完 opencode 就急着跑，然后在模型配置上卡半小时。我建议先花两分钟做三项检查，能少踩很多坑。

第一项，确认 Git 可用。opencode 在读取项目状态时依赖 Git，git --version能正常输出才好说。如果你是在一个还没初始化 Git 的目录里启动 opencode，它也能工作，但能获取的信息会少很多，Agent 对代码改动的感知会明显变弱。

第二项，检查 Node 版本。无论是通过 npm 安装还是运行时依赖，Node 版本太低都可能导致各种诡异问题。建议使用 Node 18 或更高版本。Linux 服务器上如果嫌系统源里的 Node 版本太旧，可以用 nvm 装一个较新的版本。

第三项，确认模型 API Key 已配置。opencode 本身不绑定模型，但你至少得有一种模型的接入凭证。常见的环境变量名是ANTHROPIC_API_KEY、OPENAI_API_KEY，也有第三方模型服务商自己的变量名。Linux 上修改配置后，记得让环境变量生效，比如重新 source 一下~/.bashrc或~/.zshrc，或者开一个新终端窗口。

这三项检查完，再执行opencode进入交互界面，整个体验会顺畅很多。

3. 模型接入与配置：决定 Agent 聪明程度的关键一步

3.1 支持哪些模型，怎么选才不花冤枉钱

opencode 的模型接入方式很开放，目前主流的几条路线都走得通。一是直接接 Anthropic 的 Claude 系列，很多习惯用 Claude Code 的人会直接把 API Key 拿来用；二是接 OpenAI 的 GPT 系列；三是接 Google Gemini；四是用 Ollama、LM Studio 这类工具跑本地开源模型，比如 Llama、Qwen 等。

这么多选择，日常用哪个？我的经验是分场景来看。

如果是日常写代码、改 bug、做代码审查这些偏重任务，选能力靠前的商业模型，上下文窗口越大越好。这类模型贵一些，但省心，你描述得粗略一点它也能理解到位。

如果只是跑脚本、写正则、整理文本这类简单任务，可以用便宜模型或免费额度，成本几乎为零。opencode 支持在对话中用/model命令动态切换当前模型，所以完全可以在同一个任务里，先让便宜模型做粗活，再让强模型做收尾。

这里提一下“免费模型”这个话题。确实有一些平台提供免费额度或限免模型，网上也有人在分享它们的配置方式。我的建议是：可以用来尝鲜、跑通流程，但别把重要项目的核心工作完全押在免费模型上，稳定性、隐私、上下文长度往往不如正式 API 有保障。我见过有人因为免费额度被限流，Agent 跑到一半停住，反而更浪费时间。

3.2 学会看配置文件 opencode.json

opencode 的配置集中在opencode.json文件里，项目根目录和全局配置目录各有一份。项目根目录的配置只对该项目生效，全局配置在所有项目中生效。个人经验是：模型接入、密钥这些放全局，项目专属的指令、忽略文件放项目里。

一份最简单的配置文件长这样：

{ "$schema": "https://opencode.ai/config.json", "provider": { "anthropic": { "apiKey": "{env:ANTHROPIC_API_KEY}" } }, "model": "anthropic/claude-sonnet-4", "temperature": 0.2, "theme": "opencode" }

关键字段我来拆一下。

provider是供应商配置，可以在里面写死 apiKey，也可以像我上面这样用{env:变量名}的方式从环境变量里读。强烈建议用环境变量而不是直接写在 JSON 里，尤其是团队共用电脑或配置会上传到仓库的场景，密钥泄露风险能少一点。

model指定默认模型，格式一般是供应商/模型名。temperature控制随机性，写代码我习惯调低到 0.2 左右，太高的温度会让代码风格不稳定。theme只是终端界面的外观主题。

有些模型服务商提供 OpenAI 兼容接口，可以这样配置：

{ "provider": { "openai": { "apiKey": "{env:MY_API_KEY}", "baseURL": "https://api.example.com/v1" } } }

这样配置的好处是，模型服务商用什么 SDK 都不影响，opencode 统一走 OpenAI 协议。遇到“This model is not available in your country”这类区域限制报错时，切换到支持本地区的供应商，或者换一个兼容接口的模型，通常就是修改baseURL和model两个字段的事。

Linux 服务器上改 JSON 有一点要特别注意：改完先备份，然后用jq或者至少python3 -m json.tool验证一下 JSON 格式。我见过不少人手动改完少了一个逗号，Agent 直接起不来，还一直以为是模型问题，排查半天才发现是配置语法错了。

3.3 本地模型与免费额度的搭配思路

本地模型这条路，适合两类人：一是对数据隐私特别敏感，代码不能出本机；二是想省 API 费用、且任务不复杂。opencode 配合 Ollama 的配置方式不复杂，先装好 Ollama，拉一个模型，然后在 opencode 配置里把 provider 指向本地的 Ollama 服务即可。

本地模型要注意的是，你的硬件决定体验上限。7B 左右的小模型在中高配电脑上能跑出可用的代码生成效果，但和商用大模型比仍有差距，尤其是在大仓库里做全局重构、跨文件联动这类任务，容易“顾头不顾尾”。个人建议：本地模型拿来写脚本、做简单重构、处理文档够用，真要接手老项目或批量改代码，还是交给更强的商业模型。

免费额度的模型，作为本地模型和商业模型之间的过渡方案，体验上更接近正式 API，但稳定性和动态变化是不确定因素。今天能用的免费通道，明天可能就下线了。网上时不时有人问“某某免费模型是不是下线了”，这种问题没法给出长期有效的答案，因为提供方随时可能调整策略。我的建议是：把免费额度当成备选方案，日常主力还是选一个稳定的付费通道，图省心也图可持续。

3.4 关于官方订阅和套餐的一点个人看法

opencode 官方有订阅服务的说法，社区里也有人在讨论套餐选择。从我自己的使用体验来说，要不要订阅主要取决于你想不想在模型密钥和路由配置上省时间。

自有 API Key 的路子灵活，想用哪家用哪家，成本可控，但要自己处理不同模型的差异、限流、区域可用性。官方订阅省心一点，相当于把模型调度和后端连接这些事都交给官方，代价是少了一些“折腾的乐趣”，也需要不时关注套餐变更。

我的建议是：先走自带 API Key 的路子把 opencode 整体流程跑通，确定它真的能提升你的效率之后，再考虑要不要订阅。别一上来就买套餐，结果发现自己根本不习惯 Agent 式编程，钱就白花了。工具这东西，适配自己的节奏比什么都重要。

3.5 生态增强工具：从 oh-my-claudecode 到 superpowers

用 opencode 一段时间后，你大概率会听到几个生态里的名字：oh-my-claudecode、superpowers、还有一些用于切换模型配置的小工具。它们的定位不同，但目标一致：让 Agent 用起来更顺手。

oh-my-claudecode 是一套配置和技能包的集合，里面整合了很多社区验证过的提示词、Skill 文件和工作流模板。装之前，先确认你已经理解 opencode 的基本配置结构，否则出了问题很难判断是配置冲突还是技能包本身的问题。

superpowers 则是以“给 Agent 加超能力”为卖点，本质上是一套更系统化的技能库，帮 Agent 在规划、编码、测试、重构等环节表现得更有条理。安装这类增强包之后，建议用一个小项目先跑一遍，观察 Agent 的行为变化，不要直接拿生产项目当试验田。

模型切换类工具解决的是“我在多个模型之间来回试”的痛点。你会在不同的模型之间来回试，每次手动改配置很烦，这些工具就是把切换过程自动化。用它们的时候注意一点：切换模型前把当前模型下的上下文保存好，避免丢失重要信息。

注意：这些生态工具本质上是配置和技能的“组装包”，不是 opencode 官方功能。用之前一定要看它们的兼容性说明，确认支持当前版本，否则可能出现配置不生效、Agent 行为异常等问题。

4. 五种高频玩法：把 opencode 真正用起来

4.1 接手陌生项目：让 Agent 在 5 分钟里读懂代码库

我最近接手了一个有两年历史的后端服务，代码量大、文档少、还掺杂着好几个人的编码风格。以前这种项目光梳理结构就要大半天，现在我会直接在新目录里启动 opencode，然后这么问它：

帮我梳理一下这个项目的整体架构：入口文件、核心模块、数据流、启动方式、有哪些坑需要注意。

它会自己去翻配置文件、读路由定义、看数据库模型、检查启动脚本，然后给你一份结构化的分析。这份分析不一定完全准确，但作为第一份“侦察报告”非常好用，能帮你快速建立对项目的初步理解。

接下来，我会让它做几件具体的事：

• 根据 README、依赖清单和启动脚本，整理一份本地启动步骤；
• 标记出主要的业务模块和它们之间的依赖关系；
• 找出一两个关键的入口函数，解释核心业务流程。

这里有个使用技巧：明确告诉 Agent 你的角色和目标。比如“我是一名新接手此项目的后端开发，需要快速了解支付模块”，这种限定词能把它的注意力集中到相关代码上，减少无关信息干扰。项目上下文太大时，也可以先用.opencodeignore把 node_modules、dist、build 这类目录排除掉，别让无关文件占满上下文窗口。

4.2 Skills 技能包：把常用流程沉淀成可复用的“肌肉记忆”

Skills 是 opencode 里我特别喜欢的一个机制。它的思路很简单：把一些高频、固定的工作流程写成技能文件，之后一句话就能调用。

举个例子，我经常需要给新写的接口做单元测试。传统方式每次都要重复描述“帮我写测试、注意 mock 外部依赖、覆盖率要求多少”。用 Skills 之后，只需要写一个技能文件，里面定义好完整的测试生成流程，以后直接说“给这个接口写测试”，Agent 就会按技能里定义的规范动作执行。

技能文件一般放在项目根目录的.opencode/skills或者全局配置目录下的skills文件夹里。一个技能通常包含两部分：一是描述，告诉 Agent 这个技能是干什么的、什么时候该用它；二是具体的工作流，可以是自然语言步骤，也可以是脚本或命令模板。

我建议从这几个方向开始沉淀自己的技能：

• 代码审查：检查代码风格、安全漏洞、边界条件；
• 单元测试生成：按项目规范生成测试；
• 接口文档生成：从代码注释或函数签名生成文档；
• 重构某个特定类型的代码：比如把回调改成 async/await。

社区里已经有不少人分享技能包，装别人写好的技能体验一下，再照着那个结构写自己的，上手很快。技能的设计理念是“把你重复说给 AI 听的提示词固化下来”，这是提升 Agent 效率的最直接方式。

4.3 Memory 记忆机制：让 Agent 记住你的偏好

Memory 解决的是“同一个错误不要犯两次”的问题。默认情况下，Agent 每次新会话都不记得上次你怎么要求它。有了记忆机制，它可以跨会话记住一些关键信息，比如团队代码规范、你偏好的命名风格、项目里的一些特殊约定。

实际使用中，你可以告诉 Agent“记住：这个项目的错误码统一用大写加下划线命名”，或者“以后所有新接口都必须写 OpenAPI 文档”。这些信息会被写入对应的记忆文件中，后续会话自动加载，相当于给 Agent 建了一份长期档案。

在使用记忆功能的时候，有一个度要把握：记太多琐碎信息会让记忆文件变得又长又杂，反而影响 Agent 检索关键信息。我一般只让它记住三类内容：项目中“反常识”的约定、团队强制的规范和我的个人编码偏好。其他内容尽量通过 Skills 或项目文档管理。

4.4 LSP 集成：为什么它改代码比普通聊天窗口更准

第一次听说 opencode 支持 LSP 的时候，我就知道它在改代码这件事上，和普通聊天窗口是质的不同。

LSP 是编辑器用来实现“跳转定义、查找引用、类型检查”这一系列功能的基础协议。opencode 接入 LSP 之后，它对代码的理解深度会比纯文本读取高一个档次。举个我实际遇到的例子，有个重构任务需要把一个函数的入参从两个改成三个，直接让 Agent 改。它不只是改了函数定义，还自动定位到所有调用这个函数的地方，检查了各处的传参情况，并提示哪里缺少参数。这就是 LSP 的功劳：它能看到“引用关系”，而不仅仅是“字符串匹配”。

opencode 的 LSP 配置一般在opencode.json里，指定每个语言对应的 LSP 服务器命令。比如：

{ "lsp": { "typescript": { "command": "typescript-language-server", "args": ["--stdio"] } } }

不同语言需要安装对应的 language server，完成后在配置里声明即可。因为 LSP 依赖本地的 language server，如果你在 Docker 或远程服务器上使用 opencode，记得在容器或服务器里也装好对应环境。

从体验上讲，LSP 集成让 Agent 的“代码理解能力”从“看过很多代码”提升到“确实理解这套代码”。如果你用它做大型项目，这是值得投入时间去配置的部分。

4.5 Playwright 实战：一句描述就让 Agent 复现前端 bug

前端 bug 的沟通成本一直很高。以前同事说“首页弹窗在移动端显示错位”，我得自己打开浏览器、调分辨率、找弹窗、复现错误，一来一回半小时就没了。opencode 配合 Playwright 之后，这个流程被极大压缩了。

操作思路是这样的：先让 Agent 用 Playwright 打开本地开发服务器，按照你描述的操作步骤执行，比如“点击登录，输入账号，进入首页”，然后它会截图，甚至输出控制台日志，把 bug 复现过程完整跑一遍。

有一次我遇到一个只在特定情况下出现的事件绑定问题，口头描述很难讲清，于是我跟 Agent 说：“用 Playwright 打开 localhost:3000，登录后进入设置页，点击三次保存按钮，然后告诉我前端的 console 有没有报错。”它任务是照做，几分钟后把 console 的报错贴给了我，问题一下子就定位了。

这里有一个前提：项目里需要先装好 Playwright，并且初始化浏览器环境。opencode 本身不是 Playwright 的替代品，它是“会按指令操作 Playwright 的 Agent”。配合使用时的最佳实践是，把启动命令、登录账号、测试环境地址这些信息提前告诉 Agent，省得每次重复描述。

4.6 VS Code、JetBrains 插件与桌面版：把 Agent 放进常用工作台

我在终端里用 opencode 很顺手，但遇到长代码修改时，还是想在 IDE 里直接看到 diff。这个问题有解：opencode 提供了 VS Code 插件和 JetBrains IDEA 插件，桌面版也在持续迭代。

VS Code 插件的基本用法，是在侧边栏打开 opencode 面板，输入问题和普通终端一样，但代码修改会以 diff 形式展示在编辑器里，可以直接 preview 和选择性接受。这体验比在终端里看纯文本舒服多了。JetBrains IDEA 插件的思路类似，适合用 IntelliJ 系的人。

我的建议是：终端版作为主操作界面，IDE 插件作为代码审查和修改确认的工具，两者共用配置，互补使用。IDE 插件偶尔会出现版本不同步的问题，遇到异常时先更新 opencode 核心版本，再更新插件，多数问题都能解决。

桌面版更像是一个带图形界面的 opencode 壳，把终端交互搬到窗口里，对不喜欢纯命令行的开发者友好一点，但它目前没有比 CLI 多出额外的“独家能力”，装与不装全看个人习惯。

5. 常见问题与排查实录

5.1 启动与命令层问题

我把这段时间遇到最多的问题整理成一个速查表，方便你直接定位。

5.2 模型层报错：“This model is not available in your country”

“This model is not available in your country”这类报错，本质是模型服务的区域授权限制。每家模型服务商的开放范围不一样，同一个模型可能在 A 区可用、B 区就不可用，跟你账号所属区域、支付方式、甚至访问出口都可能有关系。

处理思路有三个方向。第一，查看报错信息里提示的是哪家模型服务，去对应服务商的文档或控制台确认这个模型在你的区域是否受支持。第二，如果确认是不支持，最直接的方案是切换有明确支持该地区的模型或服务商，opencode 可以在/model命令里临时切换，也可以直接在配置文件里改默认模型。第三，检查你使用的第三方代理或兼容接口是否配置正确，很多 OpenAI 兼容服务商支持的区域更广，换一个baseURL就能绕开某个模型的区域限制。

这里不涉及任何特殊操作，就是正常的 API 成本和区域适配问题，跟你在云服务商选择不同区域节点一个道理。

5.3 服务异常与资源占用

还有一类报错，比如：

error: unexpected server error. check server logs.

这种通用报错最让人头疼，因为信息量极少。我的排查顺序是：先看是不是临时故障，重试一次；不行就检查 opencode 的日志文件，日志会具体一些；再检查网络连通性，确认能正常访问模型服务商 API；最后看是不是配置问题，比如 baseURL 写错、apiKey 失效。

另一个常见问题是内存占用高。Agent 处理大项目时会加载大量文件到上下文，内存飙升不奇怪。缓解手段包括：用.opencodeignore排除大目录、减小上下文窗口、切换更小的模型。如果服务器上同时跑多个 opencode 会话，也要注意内存上限，必要时限制并发数量。

5.4 配置不生效与缓存问题

配置文件不生效，是我被问到最多的问题之一。很多人的情况是：改了opencode.json，但 Agent 行为没有任何变化。

先确认你改对文件了。项目级配置只对当前项目生效，全局配置对所有项目生效，如果你同时有两份，项目级配置会覆盖全局的部分选项。我建议先用极简测试验证：在配置里改一个非常明显的选项，比如主题颜色，然后重启 opencode 看有没有生效。如果主题变了，说明配置链路是通的，问题出在具体参数上。

另外，opencode 的新版本对配置格式做了一些调整。如果你是从旧版本升级上来的，旧的配置文件字段可能已经不被识别。遇到这种情况，对照最新文档检查字段名和$schema路径，多数是字段名过时了。

5.5 关于模型“下线”问题的判断

社区里总会有人讨论某个免费模型还能不能用、某个第三方通道是不是下线了。我的看法是，这类问题没有长期答案，因为提供方随时可能调整策略。与其追逐不断变化的免费资源，不如建立稳定的主力链路：一个靠谱的付费 API，加一两个备用的兼容接口，再配合本地模型兜底。

opencode 的模型无关特性在这种时候体现得很好，切换模型只需改几行配置，不会像某些闭源工具一样把你锁死在一家模型上。这也是我愿意长期把它作为主力 Agent 工具的原因之一。

结尾

我把 opencode 从安装到深度使用完整走了一遍之后，最大的感受是：这类终端 Agent 正在把“写代码”从打字这件事上松绑。你不需要亲手敲出每一行代码，而是把意图描述清楚、让 Agent 去执行，然后你把关质量。对老手来说，这改变了日常工作的节奏；对新手来说，它也是理解一个陌生代码库的极好助手。

最后分享一个实战中摸索出的小建议：刚上手时不要追求一次性配齐所有功能。先搞定安装和模型连接，找一个你最痛的项目场景，比如接手工地、写测试、修 bug，用它完整做一次，再看缺什么补什么。Skill 和 Memory 这类高级玩法，等基本流程顺手后再加不迟。我一开始就是贪多，一次性装了一堆增强包，结果出了问题很难排查，反而打击信心。踏踏实实把基础链路跑通，你会发现 opencode 真正省下的不是打字时间，而是你理解代码、检索信息、验证想法的那些碎片时间。这些时间加起来，才是 Agent 工具最大的价值。