我最早知道 opencode 这个项目是在一次命令行工具分享帖里。当时我正被几个“看起来强大、实际上处处要订阅、还锁死在自家生态里”的 IDE 插件搞得有点心累就顺手在终端里试了试这个开源 Agent结果一发不可收拾。opencode 是一个开源、终端优先的 AI 编程代理能直接读写项目文件、执行命令、跑测试还能通过 Skills、Memory 和 LSP 机制把团队的代码规范沉淀成 Agent 的长期工作习惯。它不绑定某一家模型厂商GPT、Claude、Gemini、DeepSeek、Kimi、Ollama 本地模型都能接也能作为 VSCode、JetBrains 插件或桌面版使用。这篇文章不是官方文档的翻译而是我前后用了几周时间踩了不少坑之后的实操记录从安装、初始化、模型配置到 Skills/LSP 的调教再到用 Playwright 验证前端 Bug最后是高频报错的排查思路。无论你是第一次听说 opencode还是已经在命令行里用过一阵子应该都能找到点能直接上手的东西。1. 为什么是 opencode从“聊天副驾”到“终端里的结对开发”1.1 opencode 到底解决了什么问题大部分人用的 AI 编程工具本质上是一个“聊天窗口代码生成器”你在网页里贴题目它给你一段代码你再手动粘回编辑器。这个过程的问题在于AI 不了解你的项目全貌上下文一长就逻辑混乱生成的代码经常和现有架构对不上。opencode 的思路不太一样。它把 Agent 直接放进你的终端让它可以读取项目目录结构和关键文件理解当前代码库的上下文在终端里执行命令比如npm test、git diff、pnpm build根据错误输出自动尝试修复而不是把错误码丢给你通过 Skills 机制学习你团队的开发规范下次遇到同类任务能照着做通过 LSP 拿到编辑器级别的代码诊断、符号跳转、类型信息而不是纯靠“读代码猜问题”。你可以把它理解成请了一位远程实习生你给它一个任务它自己打开电脑、查看代码、运行命令、发现问题、修改文件、再跑测试然后把结果整理给你。你不需要把整个文件复制进对话框它直接操作的是你的真实工作区。1.2 和同类型 Agent 工具的横向对比现在市面上叫得上名字的终端编程 Agent 已经不少我整理了一张对比表方便你判断自己当前该用哪个对比维度opencodeClaude CodeOpenAI Codex CLIPi普通 Copilot是否开源是否否部分否默认模型可选多种Claude 系列OpenAI 系列内置模型GitHub Copilot自定义 Provider很灵活受限受限一般基本不支持Skills/规范机制支持可定制类似机制较弱一般不支持LSP 集成支持支持有限一般编辑器自带编辑器插件VSCode / JetBrains官方插件生态较浅插件较少原生支持审计与日志可保留会话记录有有一般较弱我个人的感受是如果你已经在 Anthropic 生态里深度使用 ClaudeClaude Code 确实顺滑但如果你想在不同模型之间自由切换、把团队规则沉淀成 Agent 可以执行的配置、或者想研究一个开源 Agent 的完整实现opencode 的优势就很明显。它更接近“一张白纸”允许你按照自己的开发流程来塑造它。1.3 合适与不合适的用户画像哪些人适合 opencode我的建议是平时工作流以终端为主习惯 Git、命令行构建、脚本化测试不想被单一模型厂商绑死希望同一个工具能换 GPT、Claude、Gemini 或本地模型团队有代码规范、提交信息规范、测试前置要求想让 Agent 也遵守这些约束需要审计 Agent 的改动不希望 AI 悄悄改了一堆文件却没有任何记录。哪些人不建议现在用如果你完全不用终端只想要编辑器里的“自动补全”那 opencode 对你可能太重了如果你不想配置任何 API Key只想装一个开箱即用的免费工具那它也不是最优解。opencode 的上限很高但前提是你愿意投入一点时间做初始化配置。2. 安装与初始化把 opencode 跑起来的完整流程2.1 前置环境Node.js 和 Bun 怎么选opencode 本身依赖 JavaScript 运行时。官方推荐环境是 Node.js 20 以上或者 Bun。我的建议是直接用 Node.js 的 LTS 版本因为团队环境里更常见出了问题也好排查。装好之后先确认版本node --version npm --version如果你是 macOS 用户也可以用 Homebrew 装 Bun启动速度会快一些但要注意有些第三方插件在 Bun 环境下可能表现不同没必要一开始就追求新运行时。用 Node.js 做日常主力遇到性能瓶颈再换也不迟。2.2 三种安装方式及适用场景目前我试过三种安装方式各有用武之地# 方式一npm 全局安装适合大多数平台 npm install -g opencode-ai # 方式二官方安装脚本适合快速体验 curl -fsSL https://opencode.ai/install | bash # 方式三macOS 用户使用 Homebrew brew install sst/tap/opencode我的建议是Windows 用户优先用 npm 方式因为官方脚本对 PowerShell 的支持偶尔会有权限问题macOS 用户可以用 Homebrew方便统一管理Linux 用户三种都行看个人习惯。安装完成后执行opencode --version验证。如果能看到版本号说明安装成功如果提示找不到命令先别急后面专门有一节讲这个报错。2.3 第一次启动初始化模型和 API Key安装完成后直接在项目目录下运行opencode首次启动会进入一个交互式终端界面TUI通常会自动检测当前目录并在本地生成配置文件。你可能会被引导选择一个模型 Provider或者要求设置 API Key。这里我建议第一次不要追求“全部配好”先选定一个你手上已经有 API Key 的模型跑通流程然后再慢慢加其他 Provider。比如你已经有 DeepSeek API就先配置 DeepSeek如果你有 OpenRouter也可以把 OpenRouter 作为一个统一入口。如果不想走交互式引导也可以手动创建配置文件。opencode 的配置路径一般是~/.config/opencode/opencode.jsonWindows 下对应%USERPROFILE%\.config\opencode\opencode.json。项目级配置则放在项目根目录的opencode.json。一个最小化的配置示例{ $schema: https://opencode.ai/config.json, provider: { deepseek: { apiKey: {env:DEEPSEEK_API_KEY}, model: deepseek-chat } } }注意不同版本的配置字段可能略有差异最稳妥的办法是查看本地生成的配置文件或者用编辑器的 JSON Schema 提示来补全。首次启动只要能跑通一个对话就算成功了。2.4 Windows 高频报错cmdlet 不识别 opencode这是我在 Windows 上遇到最多的一个问题opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因一般有两个一是 npm 的全局 bin 目录没有加到系统 PATH二是安装时用了非管理员终端导致全局安装目录不可写命令没有真正装上。排查步骤我建议这样走# 1. 先确认是否真的安装了 npx opencode-ai --version # 2. 查看 npm 全局路径 npm config get prefix如果npx opencode-ai --version能正常输出版本而直接运行opencode不行说明 PATH 配置有问题。把 npm 全局路径加入用户 PATH 即可。对大多数 Windows 用户来说路径通常是%APPDATA%\npm添加用户环境变量的方法是系统设置 - 环境变量 - 用户变量里的 Path - 新增上面这个路径然后重新打开终端。如果你在 PowerShell 里执行安装脚本时遇到权限问题不要在系统目录里硬装推荐先用 nvm-windows 或 fnm 管理 Node 版本再全局安装这样能省掉很多权限烦恼。2.5 升级与卸载opencode 更新频率不低我基本每周会升一次级。命令很简单opencode upgrade如果是 npm 安装的也可以用npm update -g opencode-ai卸载则是对应删除全局包npm uninstall -g opencode-ai。配置文件默认不会被卸载如果你希望彻底清理再手动删除~/.config/opencode目录即可。3. 模型接入与配置订阅、免费模型、自定义连接3.1 用opencode models查看可用模型配置模型之前最好先查看当前环境支持哪些模型。运行opencode models这个命令会列出已配置 Provider 下可用的模型包括模型 ID、上下文长度、是否支持工具调用等信息。如果你什么都没配置它通常会提示需要先设置 Provider。模型 ID 这个概念很重要。同样一个 Provider 下可能有多种模型比如 DeepSeek 有deepseek-chat和deepseek-reasonerOpenAI 有gpt-4o、gpt-4o-mini等。你需要把具体模型 ID 写进配置Agent 才知道该调用哪个。3.2 go 订阅和免费模型的定位热词里频繁出现opencode go这个“go”是官方提供的订阅服务入口可以理解为一种聚合式方案你不需要分别去开通多家厂商的 API通过 opencode go 就能按需使用多个主流模型。这类订阅方案的好处是方便一个凭证接入多个模型适合不想折腾多家 Key 的用户。但也有两个点要注意订阅额度是有限的用之前最好确认各自模型的费率避免一次大任务把额度跑光部分模型也可能存在区域可用性限制具体见第 7 章。免费模型方面opencode 同样可以接一些限时免费或额度较低的模型。我个人的建议是不要把免费模型当成生产主力它更适合用来验证流程、跑小任务、或者作为备选方案。真正处理多文件重构、复杂 Bug 排查时一个稳定的大模型比省下几毛钱重要得多。3.3 配置文件管理多个 Provider 与模型如果只是用一个 Provider配置文件很简单。但大多数人的真实情况是ChatGPT 的账号、Claude 的账号、公司内部模型、本地 Ollama 都有希望在不同任务间切换。这时候可以维护多 Provider 配置。下面是我常用的配置结构{ $schema: https://opencode.ai/config.json, provider: { openai: { apiKey: {env:OPENAI_API_KEY}, model: gpt-4o }, anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, model: claude-sonnet-4-20250514 }, deepseek: { apiKey: {env:DEEPSEEK_API_KEY}, model: deepseek-chat }, ollama: { model: qwen2.5-coder:14b, baseUrl: http://localhost:11434/v1 } } }但凡涉及敏感 Key我都不建议明文写在配置文件里。opencode 支持环境变量引用比如{env:OPENAI_API_KEY}这样可以把 Key 放到.env文件或系统环境变量中配置文件提交到 Git 也不怕泄露。3.4 搭配 CC Switch、SuperPower 这些辅助工具热词里反复出现的ccswitch 配置 opencode、opencode 接入 superpower其实是社区里常见的增强玩法。CC Switch 这类工具主要解决“多套配置快速切换”的问题。你可以把它理解成一个控制面板预先在工具里维护好不同 Provider 的配置组合然后在 Claude Code、Codex、opencode 这些 Agent 工具之间一键切换省去每次手动改环境变量、改配置文件的时间。我自己用下来的感受是如果你同时维护三套以上 Provider这个工具确实能提效。SuperPower 则更像是一个技能增强包。社区有一堆预先写好的 Skills比如代码审查、提交信息生成、SQL 优化、前端可访问性检查等。你把这些技能包克隆到 opencode 的 Skills 目录后Agent 就相当于内置了一批专家能力。装起来不复杂本质上就是复制文件和目录到约定位置具体下一章会展开讲。3.5 模型选择复杂任务与日常轻量任务的分工我见过不少人配置好模型之后不管什么任务都用同一个模型结果又贵又慢。更合理的做法是给任务分档任务类型推荐模型理由多文件重构、架构调整Claude Sonnet / GPT-4o上下文理解强改动更稳单文件小改动、补测试DeepSeek / Gemini Flash快便宜够用生成 commit message、格式化本地小模型或轻量模型延迟低不打断思路需要离线或数据不出内网Ollama Qwen Coder可完全本地运行不同模型的温度、思考模式也不一样。opencode 支持通过环境变量或配置调整部分参数但我的建议是先用默认参数跑一周再根据实际效果微调不要一开始就陷入调参黑洞。4. Skills、Memory 与 LSP把 opencode 调教成“懂规矩”的项目成员4.1 Skills给 Agent 定义可复用的技能包Skills 是 opencode 里我很喜欢的一个机制也是很多新手容易忽略的功能。简单说你可以在项目或用户目录下定义一系列“技能”每个技能由说明文档和具体规则组成Agent 在遇到匹配任务时会自动加载对应技能。一个典型的技能目录结构如下.opencode/ skills/ commit-message/ SKILL.mdSKILL.md的内容可以是 Markdown 或带 frontmatter 的格式我习惯这样写--- name: commit-message description: 当用户要求生成 commit 信息时使用 --- - 使用 Conventional Commits 规范 - 类型包括 feat / fix / refactor / docs / test / chore - 标题不超过 60 字符 - 正文可选超过一行时每行不超过 72 字符 - 不要使用 update 这种空泛的动词这样配置之后当你在 opencode 里输入“帮我生成一下这次改动的 commit message”它就会优先按照这个 Skill 的规则来生成而不是自由发挥。我踩过的一个坑是一开始把所有规范都塞进系统提示里导致每次请求都携带大量 token又慢又浪费。用 Skills 按需加载之后Agent 只在相关任务出现时读取对应规则效率提升非常明显。4.2 Memory 与 AGENTS.md项目级长期记忆Skills 解决的是“怎么做”Memory 解决的是“记住项目的长期状态”。opencode 支持项目级的记忆文件常见的做法是在项目根目录维护一个AGENTS.md。你可以把它想象成给 Agent 的“入职手册”每次启动新会话Agent 会先读这个文件了解项目的基本规则相当于拥有了跨会话的长期记忆。下面是我在一个前端项目里使用的AGENTS.md片段# AGENTS.md ## 项目信息 - 技术栈React 18 TypeScript Vite pnpm - 包管理器pnpm不要修改 pnpm-lock.yaml 除非安装新依赖 - 构建命令pnpm build - 测试命令pnpm vitest run ## 代码风格 - 组件使用函数组件和 Hooks - Props 使用 interface 定义不使用 type - 样式使用 Tailwind CSS不使用 CSS Modules - 禁止在 useEffect 中直接 setState ## 交互约定 - 新增功能必须补充测试 - 修改公共工具函数前先搜索调用方 - 不要动 src/legacy 目录下的代码有了这个文件Agent 每次在该目录下工作时都会自动读取并遵守里面的约定。这比你在每次对话开头手动强调“记住我们的代码规范”要可靠得多。如果你希望某些记忆是跨项目、全局生效的可以把类似规则放到用户级配置目录下项目级的AGENTS.md则只影响当前仓库。划分原则是团队约定放项目里个人习惯放用户级。4.3 LSP不用切 IDE 也能拿到精准代码诊断LSPLanguage Server Protocol可能很多前端同学听过但没深入用过。它本质上是一个“语言智能服务”的统一协议让编辑器或工具能够获得补全、跳转、类型检查、错误诊断这些能力。opencode 内置了 LSP 客户端这让它不再只是“靠读代码猜问题”而是能直接向语言服务器查询类型信息、诊断错误。比如在 TypeScript 项目里Agent 可以调用typescript-language-server获取某个变量到底是什么类型、某个函数有哪些重载而不需要靠肉眼推断。如果你用的是 Go 项目相应配置可以指向goplsPython 项目可以指向pyright。配置片段大致如下{ lsp: { typescript: { server: typescript-language-server, args: [--stdio] }, golang: { server: gopls } } }不用纠结字段是否完全一致关键是理解 LSP 对 Agent 的意义有了 LSPAgent 的错误判断率会明显降低。有一次我让它修改一个跨模块的函数签名它靠 LSP 自动找到了六个调用点并逐一更新而不是只改了函数定义就结束。这就是语言智能和纯文本生成的差距。4.4 一个可落地的“团队约定”配置示例把 Skills、Memory、LSP 结合起来你可以做出一个非常“懂事”的 Agent 配置目录my-project/ opencode.json AGENTS.md .opencode/ skills/ code-review/ SKILL.md playwright-test/ SKILL.md其中opencode.json负责模型和 LSP 配置AGENTS.md负责项目长期记忆skills目录负责按需加载的专业规则。这样一套配置放进代码仓库后团队其他人拉到项目时也会自动继承同样的 Agent 行为。这里要注意不要把个人 API Key 提交到仓库。opencode.json里尽量使用环境变量引用或者使用.opencode.local.json这样的私有配置来存放敏感信息。5. 实战用 opencode 接手开发项目并验证前端 Bug5.1 任务描述一个“按钮没反应”的现场前面讲了一堆配置这一章我们跑一个完整流程。假设你要接手一个 React TypeScript 项目测试反馈“结账页的提交按钮点击后没有反应控制台也没有报错”。这个场景很典型因为“无反应”比“报错”更难排查。我见过不少人在这种时候会打开 DevTools 手动点半天而用 opencode 可以直接让 Agent 带着工具去定位。5.2 第一轮会话让 Agent 带着 LSP 去排查在项目根目录下运行opencode然后输入类似这样的指令请看一下 src/pages/Checkout.tsx 里的提交按钮为什么点击后没有发起提交请求 先用 LSP 和代码搜索检查按钮是否绑定了事件不要直接改代码把可能的根因列出来。由于我在AGENTS.md里已经写了项目使用 React TypeScript 的约定Agent 会优先查看组件结构、事件绑定和相关的 Hook。实测下来它一般会做这几件事定位按钮 JSX 上的onClick绑定跳转到事件处理函数检查是否有submit逻辑查看是否有条件渲染导致点击事件被覆盖运行pnpm lint或 tsc 检查类型错误。那次排查的结果是按钮被外层form的onSubmit事件拦截而提交函数内部有一行if (!isValid) return表单校验函数在某个字段值缺失时抛了异常导致函数中断页面看起来就是“点了一下没反应”。5.3 使用 Playwright 做浏览器级验证定位到根因后接下来要验证修复方案。我不建议让 Agent 改完代码直接说“应该好了”而是让它用浏览器自动化工具跑一遍真实场景。opencode 可以协调命令行工具所以它能在项目里安装并运行 Playwright。我让 Agent 写了一个最小化测试import { test, expect } from playwright/test; test(结账页提交按钮会发起请求, async ({ page }) { await page.goto(/checkout); // 填写必要字段 await page.getByLabel(姓名).fill(张三); await page.getByLabel(电话).fill(13800138000); // 点击提交按钮 await page.getByRole(button, { name: 提交订单 }).click(); // 断言网络请求发出 await expect(page).toHaveURL(/\/api\/orders/); });Agent 会自动执行npm run dev启动本地服务再运行这个 Playwright 测试。如果测试没过它会读取 Playwright 的输出结合代码继续修复直到通过。这一步的价值很大很多 Agent 工具只会“静态生成代码”但 opencode 能真实驱动浏览器、观察网络请求、看到最终页面结果。对于前端 Bug 排查来说这是质的区别。5.4 修复、回归与审计修复完成后Agent 通常还会顺便跑一次全量测试确保改动没有影响其他功能。最后它会给我一份改动摘要列出修改了哪些文件、为什么这样改、测试结果如何。审计方面opencode 的会话记录和改动记录是保留在本地的。我习惯用git diff再复查一遍 Agent 的改动毕竟代码规范可以靠规则约束但业务逻辑的正确性还是要人来确认。如果你有团队协作需求也可以把会话日志导出发给同事做 review这对远程团队尤其友好。6. 编辑器与桌面端体验VSCode、JetBrains、桌面版6.1 VSCode 插件侧边栏协作虽然 opencode 主打终端但对很多不习惯 TUI 的开发者来说VSCode 插件是更友好的入口。在扩展市场搜索 opencode安装官方插件后它会在侧边栏新增一个面板。你可以直接打开项目目录选择当前激活文件的上下文然后给 Agent 下发指令。插件内部会调用终端里的 opencode CLI所以终端里能用的 Skills、LSP、Playwright 能力在 VSCode 里同样可用。我的使用方式是终端里跑重活VSCode 里做轻量 review。插件面板适合“选中一段代码让 Agent 解释或重构”结合 Diff 视图看改动非常直观。6.2 JetBrains IDEA 插件热词里有opencode jetbrains idea 插件我自己在 IDEA 里也试过。JetBrains 系的插件体验和 VSCode 插件类似但有一个特别值得提的点它和 IDEA 的构建系统集成得更好。对于 Java/Maven/Gradle 项目你可以在opencode.json或插件设置里指定构建命令。比如{ commands: { build: mvn -q compile, test: mvn -q test } }这样 Agent 在执行编译和测试时会走 Maven 流程而不是猜测项目怎么构建。这是我在 Java 项目中使用 opencode 最重要的一条配置。另外IDEA 里打开 LSP 时可能和 IDE 自带语言服务器产生重复诊断。遇到这种情况可以在插件配置中关闭 opencode 的 LSP只让它依赖 IDE 提供智能上下文即可。6.3 桌面版与 Web 端如果你完全不想碰命令行opencode 桌面版也能满足日常需求。桌面版提供图形化的项目打开、会话时间线、日志查看和模型快捷切换。它适合给项目管理者或不熟悉终端的人做演示也适合调试复杂会话时直观地回溯每一步。我建议桌面版和 CLI 搭配使用日常开发用 CLI 效率更高复盘和审计时用桌面版看着更清楚两边的会话是共通的不冲突。6.4 团队协作场景Session 与日志在团队里推广 opencode 时最重要的不是装几个插件而是建立“可复现的会话记录”机制。我一般要求团队成员把重要的 Agent 会话导出为文件或者至少保留一份git diff输出。opencode 的会话日志会记录 Agent 的每一步操作包括调用了什么命令、读取了哪些文件、改了什么内容。这种审计能力在多人协作中很实用。当有人报告“Agent 改坏了东西”你可以直接翻会话日志定位是哪个步骤引入了问题而不需要从头到尾盲猜。7. 高频报错排查与我的使用心得7.1 常见报错对照表使用过程中有几个报错几乎每个人都会遇到。我整理了一个对照表报错现象常见原因解决方案无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称npm 全局路径未加入 PATH执行npm config get prefix把输出目录加入用户 PATH重开终端This model is not available in your country模型服务方有区域限制不要尝试绕过限制改用你所在区域可合法访问的模型或本地模型error: unexpected server error. check server logs服务端故障、配额耗尽、网络不稳定检查服务商状态页查看本地日志稍后重试或切换备选 Provider配置文件明明写了字段却不生效opencode 版本更新导致 schema 变化打开opencode.json的 JSON Schema 提示按提示修正字段名中文路径导致命令执行失败部分终端工具对非 ASCII 路径处理不好尽量使用英文目录名或调整终端编码为 UTF-87.2 模型区域不可用的合规处理This model is not available in your country这个问题最近热搜里也出现得很频繁。这种报错不代表 opencode 有问题而是模型服务商基于账号所属区域做的可用性限制。我的建议是不要试图通过任何绕过手段去访问受限模型这既可能违反服务条款也不稳定。更务实的做法是切换同 Provider 下其他可用模型换成你所在区域支持的其他模型服务比如国内可用的 DeepSeek、Kimi、通义千问、智谱 GLM 等使用本地模型比如通过 Ollama 跑 Qwen Coder、DeepSeek 蒸馏模型等。本地模型的好处是数据不出本机也不受区域影响适合对延迟和数据安全要求高的场景。虽然跑大模型对硬件有要求但现在的量化模型在普通开发机上已经能跑出可用的效果。7.3 身份困惑选 opencode、codex、claude code 还是 pi热词里有个问题很有意思opencode codex claude code pi 哪个 agent 好用。其实没有标准答案我的判断逻辑是如果你看重开源、可定制、多模型自由切换选 opencode如果你重度使用 Claude 且已经订阅了 Anthropic 的 APIClaude Code 的开箱体验确实好如果你主要在 OpenAI 生态里习惯了 Codex 的交互可以继续用 Codex如果你只需要一个轻量 Agent 做简单问答和代码片段pi 或类似小工具就够。我自己把 opencode 当主力是因为它不限制我用哪个模型。今天项目需要更长的上下文我可以换个上下文窗口更大的模型明天任务比较简单我切到便宜的小模型避免浪费额度。这种自由度是闭源工具很难给的。7.4 几条让我工作效率明显提升的小习惯最后分享几个我养成的使用习惯它们比任何配置技巧都更重要新项目的第一件事不是写业务代码而是写AGENTS.md。没有这份文件Agent 就像没有入职培训的新人有了它后续每一次会话都更稳定。让 Agent “说清楚再动手”。在指令里加上“先列出排查思路再改代码”能明显减少它瞎改的情况。重要改动必须有一条可执行的验证命令。无论是测试、lint 还是构建只要 Agent 能自己跑它就不再是盲改。定期清空会话。opencode 的上下文是有限的一个长时间不结束的会话会越来越“糊涂”。遇到思路混乱时新建一个会话比反复纠正更高效。我个人现在几乎每天都会打开 opencode而且越来越觉得真正拉开效率差距的不是模型有多强而是你有没有把项目状态、规则和验证手段完整地交给 Agent。如果你刚开始用我建议第一件事不是折腾模型配置而是先写一份简短的AGENTS.md并跑通一条测试命令然后再让 Agent 开始改代码。等它真正理解了你的项目之后你会发现自己从“写代码的人”慢慢变成了“验收代码的人”。
opencode开源终端AI编程代理：从安装到实战配置指南
我最早知道 opencode 这个项目是在一次命令行工具分享帖里。当时我正被几个“看起来强大、实际上处处要订阅、还锁死在自家生态里”的 IDE 插件搞得有点心累就顺手在终端里试了试这个开源 Agent结果一发不可收拾。opencode 是一个开源、终端优先的 AI 编程代理能直接读写项目文件、执行命令、跑测试还能通过 Skills、Memory 和 LSP 机制把团队的代码规范沉淀成 Agent 的长期工作习惯。它不绑定某一家模型厂商GPT、Claude、Gemini、DeepSeek、Kimi、Ollama 本地模型都能接也能作为 VSCode、JetBrains 插件或桌面版使用。这篇文章不是官方文档的翻译而是我前后用了几周时间踩了不少坑之后的实操记录从安装、初始化、模型配置到 Skills/LSP 的调教再到用 Playwright 验证前端 Bug最后是高频报错的排查思路。无论你是第一次听说 opencode还是已经在命令行里用过一阵子应该都能找到点能直接上手的东西。1. 为什么是 opencode从“聊天副驾”到“终端里的结对开发”1.1 opencode 到底解决了什么问题大部分人用的 AI 编程工具本质上是一个“聊天窗口代码生成器”你在网页里贴题目它给你一段代码你再手动粘回编辑器。这个过程的问题在于AI 不了解你的项目全貌上下文一长就逻辑混乱生成的代码经常和现有架构对不上。opencode 的思路不太一样。它把 Agent 直接放进你的终端让它可以读取项目目录结构和关键文件理解当前代码库的上下文在终端里执行命令比如npm test、git diff、pnpm build根据错误输出自动尝试修复而不是把错误码丢给你通过 Skills 机制学习你团队的开发规范下次遇到同类任务能照着做通过 LSP 拿到编辑器级别的代码诊断、符号跳转、类型信息而不是纯靠“读代码猜问题”。你可以把它理解成请了一位远程实习生你给它一个任务它自己打开电脑、查看代码、运行命令、发现问题、修改文件、再跑测试然后把结果整理给你。你不需要把整个文件复制进对话框它直接操作的是你的真实工作区。1.2 和同类型 Agent 工具的横向对比现在市面上叫得上名字的终端编程 Agent 已经不少我整理了一张对比表方便你判断自己当前该用哪个对比维度opencodeClaude CodeOpenAI Codex CLIPi普通 Copilot是否开源是否否部分否默认模型可选多种Claude 系列OpenAI 系列内置模型GitHub Copilot自定义 Provider很灵活受限受限一般基本不支持Skills/规范机制支持可定制类似机制较弱一般不支持LSP 集成支持支持有限一般编辑器自带编辑器插件VSCode / JetBrains官方插件生态较浅插件较少原生支持审计与日志可保留会话记录有有一般较弱我个人的感受是如果你已经在 Anthropic 生态里深度使用 ClaudeClaude Code 确实顺滑但如果你想在不同模型之间自由切换、把团队规则沉淀成 Agent 可以执行的配置、或者想研究一个开源 Agent 的完整实现opencode 的优势就很明显。它更接近“一张白纸”允许你按照自己的开发流程来塑造它。1.3 合适与不合适的用户画像哪些人适合 opencode我的建议是平时工作流以终端为主习惯 Git、命令行构建、脚本化测试不想被单一模型厂商绑死希望同一个工具能换 GPT、Claude、Gemini 或本地模型团队有代码规范、提交信息规范、测试前置要求想让 Agent 也遵守这些约束需要审计 Agent 的改动不希望 AI 悄悄改了一堆文件却没有任何记录。哪些人不建议现在用如果你完全不用终端只想要编辑器里的“自动补全”那 opencode 对你可能太重了如果你不想配置任何 API Key只想装一个开箱即用的免费工具那它也不是最优解。opencode 的上限很高但前提是你愿意投入一点时间做初始化配置。2. 安装与初始化把 opencode 跑起来的完整流程2.1 前置环境Node.js 和 Bun 怎么选opencode 本身依赖 JavaScript 运行时。官方推荐环境是 Node.js 20 以上或者 Bun。我的建议是直接用 Node.js 的 LTS 版本因为团队环境里更常见出了问题也好排查。装好之后先确认版本node --version npm --version如果你是 macOS 用户也可以用 Homebrew 装 Bun启动速度会快一些但要注意有些第三方插件在 Bun 环境下可能表现不同没必要一开始就追求新运行时。用 Node.js 做日常主力遇到性能瓶颈再换也不迟。2.2 三种安装方式及适用场景目前我试过三种安装方式各有用武之地# 方式一npm 全局安装适合大多数平台 npm install -g opencode-ai # 方式二官方安装脚本适合快速体验 curl -fsSL https://opencode.ai/install | bash # 方式三macOS 用户使用 Homebrew brew install sst/tap/opencode我的建议是Windows 用户优先用 npm 方式因为官方脚本对 PowerShell 的支持偶尔会有权限问题macOS 用户可以用 Homebrew方便统一管理Linux 用户三种都行看个人习惯。安装完成后执行opencode --version验证。如果能看到版本号说明安装成功如果提示找不到命令先别急后面专门有一节讲这个报错。2.3 第一次启动初始化模型和 API Key安装完成后直接在项目目录下运行opencode首次启动会进入一个交互式终端界面TUI通常会自动检测当前目录并在本地生成配置文件。你可能会被引导选择一个模型 Provider或者要求设置 API Key。这里我建议第一次不要追求“全部配好”先选定一个你手上已经有 API Key 的模型跑通流程然后再慢慢加其他 Provider。比如你已经有 DeepSeek API就先配置 DeepSeek如果你有 OpenRouter也可以把 OpenRouter 作为一个统一入口。如果不想走交互式引导也可以手动创建配置文件。opencode 的配置路径一般是~/.config/opencode/opencode.jsonWindows 下对应%USERPROFILE%\.config\opencode\opencode.json。项目级配置则放在项目根目录的opencode.json。一个最小化的配置示例{ $schema: https://opencode.ai/config.json, provider: { deepseek: { apiKey: {env:DEEPSEEK_API_KEY}, model: deepseek-chat } } }注意不同版本的配置字段可能略有差异最稳妥的办法是查看本地生成的配置文件或者用编辑器的 JSON Schema 提示来补全。首次启动只要能跑通一个对话就算成功了。2.4 Windows 高频报错cmdlet 不识别 opencode这是我在 Windows 上遇到最多的一个问题opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因一般有两个一是 npm 的全局 bin 目录没有加到系统 PATH二是安装时用了非管理员终端导致全局安装目录不可写命令没有真正装上。排查步骤我建议这样走# 1. 先确认是否真的安装了 npx opencode-ai --version # 2. 查看 npm 全局路径 npm config get prefix如果npx opencode-ai --version能正常输出版本而直接运行opencode不行说明 PATH 配置有问题。把 npm 全局路径加入用户 PATH 即可。对大多数 Windows 用户来说路径通常是%APPDATA%\npm添加用户环境变量的方法是系统设置 - 环境变量 - 用户变量里的 Path - 新增上面这个路径然后重新打开终端。如果你在 PowerShell 里执行安装脚本时遇到权限问题不要在系统目录里硬装推荐先用 nvm-windows 或 fnm 管理 Node 版本再全局安装这样能省掉很多权限烦恼。2.5 升级与卸载opencode 更新频率不低我基本每周会升一次级。命令很简单opencode upgrade如果是 npm 安装的也可以用npm update -g opencode-ai卸载则是对应删除全局包npm uninstall -g opencode-ai。配置文件默认不会被卸载如果你希望彻底清理再手动删除~/.config/opencode目录即可。3. 模型接入与配置订阅、免费模型、自定义连接3.1 用opencode models查看可用模型配置模型之前最好先查看当前环境支持哪些模型。运行opencode models这个命令会列出已配置 Provider 下可用的模型包括模型 ID、上下文长度、是否支持工具调用等信息。如果你什么都没配置它通常会提示需要先设置 Provider。模型 ID 这个概念很重要。同样一个 Provider 下可能有多种模型比如 DeepSeek 有deepseek-chat和deepseek-reasonerOpenAI 有gpt-4o、gpt-4o-mini等。你需要把具体模型 ID 写进配置Agent 才知道该调用哪个。3.2 go 订阅和免费模型的定位热词里频繁出现opencode go这个“go”是官方提供的订阅服务入口可以理解为一种聚合式方案你不需要分别去开通多家厂商的 API通过 opencode go 就能按需使用多个主流模型。这类订阅方案的好处是方便一个凭证接入多个模型适合不想折腾多家 Key 的用户。但也有两个点要注意订阅额度是有限的用之前最好确认各自模型的费率避免一次大任务把额度跑光部分模型也可能存在区域可用性限制具体见第 7 章。免费模型方面opencode 同样可以接一些限时免费或额度较低的模型。我个人的建议是不要把免费模型当成生产主力它更适合用来验证流程、跑小任务、或者作为备选方案。真正处理多文件重构、复杂 Bug 排查时一个稳定的大模型比省下几毛钱重要得多。3.3 配置文件管理多个 Provider 与模型如果只是用一个 Provider配置文件很简单。但大多数人的真实情况是ChatGPT 的账号、Claude 的账号、公司内部模型、本地 Ollama 都有希望在不同任务间切换。这时候可以维护多 Provider 配置。下面是我常用的配置结构{ $schema: https://opencode.ai/config.json, provider: { openai: { apiKey: {env:OPENAI_API_KEY}, model: gpt-4o }, anthropic: { apiKey: {env:ANTHROPIC_API_KEY}, model: claude-sonnet-4-20250514 }, deepseek: { apiKey: {env:DEEPSEEK_API_KEY}, model: deepseek-chat }, ollama: { model: qwen2.5-coder:14b, baseUrl: http://localhost:11434/v1 } } }但凡涉及敏感 Key我都不建议明文写在配置文件里。opencode 支持环境变量引用比如{env:OPENAI_API_KEY}这样可以把 Key 放到.env文件或系统环境变量中配置文件提交到 Git 也不怕泄露。3.4 搭配 CC Switch、SuperPower 这些辅助工具热词里反复出现的ccswitch 配置 opencode、opencode 接入 superpower其实是社区里常见的增强玩法。CC Switch 这类工具主要解决“多套配置快速切换”的问题。你可以把它理解成一个控制面板预先在工具里维护好不同 Provider 的配置组合然后在 Claude Code、Codex、opencode 这些 Agent 工具之间一键切换省去每次手动改环境变量、改配置文件的时间。我自己用下来的感受是如果你同时维护三套以上 Provider这个工具确实能提效。SuperPower 则更像是一个技能增强包。社区有一堆预先写好的 Skills比如代码审查、提交信息生成、SQL 优化、前端可访问性检查等。你把这些技能包克隆到 opencode 的 Skills 目录后Agent 就相当于内置了一批专家能力。装起来不复杂本质上就是复制文件和目录到约定位置具体下一章会展开讲。3.5 模型选择复杂任务与日常轻量任务的分工我见过不少人配置好模型之后不管什么任务都用同一个模型结果又贵又慢。更合理的做法是给任务分档任务类型推荐模型理由多文件重构、架构调整Claude Sonnet / GPT-4o上下文理解强改动更稳单文件小改动、补测试DeepSeek / Gemini Flash快便宜够用生成 commit message、格式化本地小模型或轻量模型延迟低不打断思路需要离线或数据不出内网Ollama Qwen Coder可完全本地运行不同模型的温度、思考模式也不一样。opencode 支持通过环境变量或配置调整部分参数但我的建议是先用默认参数跑一周再根据实际效果微调不要一开始就陷入调参黑洞。4. Skills、Memory 与 LSP把 opencode 调教成“懂规矩”的项目成员4.1 Skills给 Agent 定义可复用的技能包Skills 是 opencode 里我很喜欢的一个机制也是很多新手容易忽略的功能。简单说你可以在项目或用户目录下定义一系列“技能”每个技能由说明文档和具体规则组成Agent 在遇到匹配任务时会自动加载对应技能。一个典型的技能目录结构如下.opencode/ skills/ commit-message/ SKILL.mdSKILL.md的内容可以是 Markdown 或带 frontmatter 的格式我习惯这样写--- name: commit-message description: 当用户要求生成 commit 信息时使用 --- - 使用 Conventional Commits 规范 - 类型包括 feat / fix / refactor / docs / test / chore - 标题不超过 60 字符 - 正文可选超过一行时每行不超过 72 字符 - 不要使用 update 这种空泛的动词这样配置之后当你在 opencode 里输入“帮我生成一下这次改动的 commit message”它就会优先按照这个 Skill 的规则来生成而不是自由发挥。我踩过的一个坑是一开始把所有规范都塞进系统提示里导致每次请求都携带大量 token又慢又浪费。用 Skills 按需加载之后Agent 只在相关任务出现时读取对应规则效率提升非常明显。4.2 Memory 与 AGENTS.md项目级长期记忆Skills 解决的是“怎么做”Memory 解决的是“记住项目的长期状态”。opencode 支持项目级的记忆文件常见的做法是在项目根目录维护一个AGENTS.md。你可以把它想象成给 Agent 的“入职手册”每次启动新会话Agent 会先读这个文件了解项目的基本规则相当于拥有了跨会话的长期记忆。下面是我在一个前端项目里使用的AGENTS.md片段# AGENTS.md ## 项目信息 - 技术栈React 18 TypeScript Vite pnpm - 包管理器pnpm不要修改 pnpm-lock.yaml 除非安装新依赖 - 构建命令pnpm build - 测试命令pnpm vitest run ## 代码风格 - 组件使用函数组件和 Hooks - Props 使用 interface 定义不使用 type - 样式使用 Tailwind CSS不使用 CSS Modules - 禁止在 useEffect 中直接 setState ## 交互约定 - 新增功能必须补充测试 - 修改公共工具函数前先搜索调用方 - 不要动 src/legacy 目录下的代码有了这个文件Agent 每次在该目录下工作时都会自动读取并遵守里面的约定。这比你在每次对话开头手动强调“记住我们的代码规范”要可靠得多。如果你希望某些记忆是跨项目、全局生效的可以把类似规则放到用户级配置目录下项目级的AGENTS.md则只影响当前仓库。划分原则是团队约定放项目里个人习惯放用户级。4.3 LSP不用切 IDE 也能拿到精准代码诊断LSPLanguage Server Protocol可能很多前端同学听过但没深入用过。它本质上是一个“语言智能服务”的统一协议让编辑器或工具能够获得补全、跳转、类型检查、错误诊断这些能力。opencode 内置了 LSP 客户端这让它不再只是“靠读代码猜问题”而是能直接向语言服务器查询类型信息、诊断错误。比如在 TypeScript 项目里Agent 可以调用typescript-language-server获取某个变量到底是什么类型、某个函数有哪些重载而不需要靠肉眼推断。如果你用的是 Go 项目相应配置可以指向goplsPython 项目可以指向pyright。配置片段大致如下{ lsp: { typescript: { server: typescript-language-server, args: [--stdio] }, golang: { server: gopls } } }不用纠结字段是否完全一致关键是理解 LSP 对 Agent 的意义有了 LSPAgent 的错误判断率会明显降低。有一次我让它修改一个跨模块的函数签名它靠 LSP 自动找到了六个调用点并逐一更新而不是只改了函数定义就结束。这就是语言智能和纯文本生成的差距。4.4 一个可落地的“团队约定”配置示例把 Skills、Memory、LSP 结合起来你可以做出一个非常“懂事”的 Agent 配置目录my-project/ opencode.json AGENTS.md .opencode/ skills/ code-review/ SKILL.md playwright-test/ SKILL.md其中opencode.json负责模型和 LSP 配置AGENTS.md负责项目长期记忆skills目录负责按需加载的专业规则。这样一套配置放进代码仓库后团队其他人拉到项目时也会自动继承同样的 Agent 行为。这里要注意不要把个人 API Key 提交到仓库。opencode.json里尽量使用环境变量引用或者使用.opencode.local.json这样的私有配置来存放敏感信息。5. 实战用 opencode 接手开发项目并验证前端 Bug5.1 任务描述一个“按钮没反应”的现场前面讲了一堆配置这一章我们跑一个完整流程。假设你要接手一个 React TypeScript 项目测试反馈“结账页的提交按钮点击后没有反应控制台也没有报错”。这个场景很典型因为“无反应”比“报错”更难排查。我见过不少人在这种时候会打开 DevTools 手动点半天而用 opencode 可以直接让 Agent 带着工具去定位。5.2 第一轮会话让 Agent 带着 LSP 去排查在项目根目录下运行opencode然后输入类似这样的指令请看一下 src/pages/Checkout.tsx 里的提交按钮为什么点击后没有发起提交请求 先用 LSP 和代码搜索检查按钮是否绑定了事件不要直接改代码把可能的根因列出来。由于我在AGENTS.md里已经写了项目使用 React TypeScript 的约定Agent 会优先查看组件结构、事件绑定和相关的 Hook。实测下来它一般会做这几件事定位按钮 JSX 上的onClick绑定跳转到事件处理函数检查是否有submit逻辑查看是否有条件渲染导致点击事件被覆盖运行pnpm lint或 tsc 检查类型错误。那次排查的结果是按钮被外层form的onSubmit事件拦截而提交函数内部有一行if (!isValid) return表单校验函数在某个字段值缺失时抛了异常导致函数中断页面看起来就是“点了一下没反应”。5.3 使用 Playwright 做浏览器级验证定位到根因后接下来要验证修复方案。我不建议让 Agent 改完代码直接说“应该好了”而是让它用浏览器自动化工具跑一遍真实场景。opencode 可以协调命令行工具所以它能在项目里安装并运行 Playwright。我让 Agent 写了一个最小化测试import { test, expect } from playwright/test; test(结账页提交按钮会发起请求, async ({ page }) { await page.goto(/checkout); // 填写必要字段 await page.getByLabel(姓名).fill(张三); await page.getByLabel(电话).fill(13800138000); // 点击提交按钮 await page.getByRole(button, { name: 提交订单 }).click(); // 断言网络请求发出 await expect(page).toHaveURL(/\/api\/orders/); });Agent 会自动执行npm run dev启动本地服务再运行这个 Playwright 测试。如果测试没过它会读取 Playwright 的输出结合代码继续修复直到通过。这一步的价值很大很多 Agent 工具只会“静态生成代码”但 opencode 能真实驱动浏览器、观察网络请求、看到最终页面结果。对于前端 Bug 排查来说这是质的区别。5.4 修复、回归与审计修复完成后Agent 通常还会顺便跑一次全量测试确保改动没有影响其他功能。最后它会给我一份改动摘要列出修改了哪些文件、为什么这样改、测试结果如何。审计方面opencode 的会话记录和改动记录是保留在本地的。我习惯用git diff再复查一遍 Agent 的改动毕竟代码规范可以靠规则约束但业务逻辑的正确性还是要人来确认。如果你有团队协作需求也可以把会话日志导出发给同事做 review这对远程团队尤其友好。6. 编辑器与桌面端体验VSCode、JetBrains、桌面版6.1 VSCode 插件侧边栏协作虽然 opencode 主打终端但对很多不习惯 TUI 的开发者来说VSCode 插件是更友好的入口。在扩展市场搜索 opencode安装官方插件后它会在侧边栏新增一个面板。你可以直接打开项目目录选择当前激活文件的上下文然后给 Agent 下发指令。插件内部会调用终端里的 opencode CLI所以终端里能用的 Skills、LSP、Playwright 能力在 VSCode 里同样可用。我的使用方式是终端里跑重活VSCode 里做轻量 review。插件面板适合“选中一段代码让 Agent 解释或重构”结合 Diff 视图看改动非常直观。6.2 JetBrains IDEA 插件热词里有opencode jetbrains idea 插件我自己在 IDEA 里也试过。JetBrains 系的插件体验和 VSCode 插件类似但有一个特别值得提的点它和 IDEA 的构建系统集成得更好。对于 Java/Maven/Gradle 项目你可以在opencode.json或插件设置里指定构建命令。比如{ commands: { build: mvn -q compile, test: mvn -q test } }这样 Agent 在执行编译和测试时会走 Maven 流程而不是猜测项目怎么构建。这是我在 Java 项目中使用 opencode 最重要的一条配置。另外IDEA 里打开 LSP 时可能和 IDE 自带语言服务器产生重复诊断。遇到这种情况可以在插件配置中关闭 opencode 的 LSP只让它依赖 IDE 提供智能上下文即可。6.3 桌面版与 Web 端如果你完全不想碰命令行opencode 桌面版也能满足日常需求。桌面版提供图形化的项目打开、会话时间线、日志查看和模型快捷切换。它适合给项目管理者或不熟悉终端的人做演示也适合调试复杂会话时直观地回溯每一步。我建议桌面版和 CLI 搭配使用日常开发用 CLI 效率更高复盘和审计时用桌面版看着更清楚两边的会话是共通的不冲突。6.4 团队协作场景Session 与日志在团队里推广 opencode 时最重要的不是装几个插件而是建立“可复现的会话记录”机制。我一般要求团队成员把重要的 Agent 会话导出为文件或者至少保留一份git diff输出。opencode 的会话日志会记录 Agent 的每一步操作包括调用了什么命令、读取了哪些文件、改了什么内容。这种审计能力在多人协作中很实用。当有人报告“Agent 改坏了东西”你可以直接翻会话日志定位是哪个步骤引入了问题而不需要从头到尾盲猜。7. 高频报错排查与我的使用心得7.1 常见报错对照表使用过程中有几个报错几乎每个人都会遇到。我整理了一个对照表报错现象常见原因解决方案无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称npm 全局路径未加入 PATH执行npm config get prefix把输出目录加入用户 PATH重开终端This model is not available in your country模型服务方有区域限制不要尝试绕过限制改用你所在区域可合法访问的模型或本地模型error: unexpected server error. check server logs服务端故障、配额耗尽、网络不稳定检查服务商状态页查看本地日志稍后重试或切换备选 Provider配置文件明明写了字段却不生效opencode 版本更新导致 schema 变化打开opencode.json的 JSON Schema 提示按提示修正字段名中文路径导致命令执行失败部分终端工具对非 ASCII 路径处理不好尽量使用英文目录名或调整终端编码为 UTF-87.2 模型区域不可用的合规处理This model is not available in your country这个问题最近热搜里也出现得很频繁。这种报错不代表 opencode 有问题而是模型服务商基于账号所属区域做的可用性限制。我的建议是不要试图通过任何绕过手段去访问受限模型这既可能违反服务条款也不稳定。更务实的做法是切换同 Provider 下其他可用模型换成你所在区域支持的其他模型服务比如国内可用的 DeepSeek、Kimi、通义千问、智谱 GLM 等使用本地模型比如通过 Ollama 跑 Qwen Coder、DeepSeek 蒸馏模型等。本地模型的好处是数据不出本机也不受区域影响适合对延迟和数据安全要求高的场景。虽然跑大模型对硬件有要求但现在的量化模型在普通开发机上已经能跑出可用的效果。7.3 身份困惑选 opencode、codex、claude code 还是 pi热词里有个问题很有意思opencode codex claude code pi 哪个 agent 好用。其实没有标准答案我的判断逻辑是如果你看重开源、可定制、多模型自由切换选 opencode如果你重度使用 Claude 且已经订阅了 Anthropic 的 APIClaude Code 的开箱体验确实好如果你主要在 OpenAI 生态里习惯了 Codex 的交互可以继续用 Codex如果你只需要一个轻量 Agent 做简单问答和代码片段pi 或类似小工具就够。我自己把 opencode 当主力是因为它不限制我用哪个模型。今天项目需要更长的上下文我可以换个上下文窗口更大的模型明天任务比较简单我切到便宜的小模型避免浪费额度。这种自由度是闭源工具很难给的。7.4 几条让我工作效率明显提升的小习惯最后分享几个我养成的使用习惯它们比任何配置技巧都更重要新项目的第一件事不是写业务代码而是写AGENTS.md。没有这份文件Agent 就像没有入职培训的新人有了它后续每一次会话都更稳定。让 Agent “说清楚再动手”。在指令里加上“先列出排查思路再改代码”能明显减少它瞎改的情况。重要改动必须有一条可执行的验证命令。无论是测试、lint 还是构建只要 Agent 能自己跑它就不再是盲改。定期清空会话。opencode 的上下文是有限的一个长时间不结束的会话会越来越“糊涂”。遇到思路混乱时新建一个会话比反复纠正更高效。我个人现在几乎每天都会打开 opencode而且越来越觉得真正拉开效率差距的不是模型有多强而是你有没有把项目状态、规则和验证手段完整地交给 Agent。如果你刚开始用我建议第一件事不是折腾模型配置而是先写一份简短的AGENTS.md并跑通一条测试命令然后再让 Agent 开始改代码。等它真正理解了你的项目之后你会发现自己从“写代码的人”慢慢变成了“验收代码的人”。
