这个 opencode 我前后用了三周左右从最开始在终端里敲命令都报错到现在把整个日常开发流程都迁过来了中间踩了一堆别人没怎么写过细节的坑。如果你也想把工作流从在编辑器里问 AI切换到在终端里让 AI 自己动手改项目这篇应该能帮你省下不少折腾时间。我会把安装、模型配置、Skills、Memory、编辑器插件、桌面版以及几个真实项目里跑通的经验一口气讲完不绕弯子。1. opencode 是什么它到底解决了我的什么问题1.1 从聊天补全到自己动手的编码代理过去一年大家熟悉的 AI 编程工具大多是编辑器插件形态你打开某个文件选中一段代码让 AI 帮你补全、解释或者生成单测。这个模式足够方便但有一个天花板——AI 的视野基本局限在当前打开的文件和聊天窗口里粘贴的片段它看不到项目全貌更没法自己去跑测试、跟进报错。opencode 是另一种思路。它是一个跑在终端里的开源编码代理你给它一个任务它能自己读项目文件、搜索代码、执行命令、修改文件并且每个敏感动作前会征求你同意。我第一次感受到这种差异是让它去修一个老项目的单元测试。以前用 IDE 插件我得把测试失败的堆栈、相关代码、依赖关系一层层复制给它来回好几轮用 opencode 时我只需要说跑一下 service 层的测试把失败的修好它自己会去执行测试、看报错、定位代码、改文件然后再跑一遍验证。整个过程我只需要在它准备改代码的时候按几次确认键。这个代理式的工作方式才是 opencode 和普通 AI 编程助手的本质区别。它不是更聪明的补全工具而是一个有执行能力的 AI 协作者。1.2 它和 Claude Code、Codex 到底是什么关系opencode 是哪家公司的这个问题很多人问过。它由做 Serverless 框架SST的那个团队开源TypeScript 编写目标是做一个开放的、不绑死单一模型的编码代理运行时。和它对比最多的两个工具是 Claude Code 和 Codex CLI。我自己三个都体验过说下真实感受对比维度opencodeClaude CodeCodex CLI模型锁定多厂商/本地模型主要绑 Anthropic主要绑 OpenAI开源是否是Skills 技能机制完整支持支持较弱编辑器扩展VS Code、JetBrains官方集成有限少本地模型接入容易麻烦一般不推荐日常上手成本中等低低Claude Code 的执行质量确实很高但账号和模型选择被限制得很死想换模型得绕很多弯Codex CLI 如果你用 OpenAI 生态体验也不错。opencode 最大的价值是把前端交互、权限控制、任务编排做成了一个统一框架后端模型你可以自由选择。对我来说这意味着我可以用一套操作习惯随时在 DeepSeek、GLM、Kimi、Ollama 本地模型之间切换而不是被迫绑定某一家。1.3 什么阶段的人适合切过来先泼一盆冷水如果你目前的 AI 用途还停留在帮我写个函数解释这段代码这种输入输出式问答opencode 对你来说反而显得重。它有学习成本要理解配置、懂一点命令行操作、要对项目结构有一定认知。真正受益的是这几类人频繁接手不熟悉的项目希望 AI 快速梳理结构和调用链写大量重复性代码比如接口实现、DTO 转换、测试用例需要跨文件重构想让 AI 自己找到所有引用并修改对模型选择有要求想用更便宜甚至免费的模型完成日常编码简单说opencode 适合愿意把 AI 当实习生来带的开发者。这也是我写这篇文章的核心出发点。2. 安装和 Windows 下最让人抓狂的启动报错2.1 两条安装路径一条最通用opencode 的官方安装脚本适用于 macOS 和 Linuxcurl -fsSL https://opencode.ai/install | bash但如果你在 Windows 上或者搞不清自己机器的环境直接用 npm 安装最稳npm install -g opencode-ai安装完成后验证是否成功opencode --version能输出版本号说明第一步走通了。这里有个小细节npm 包的名称是opencode-ai但安装后暴露给终端的命令是opencode。如果你在某个教程里看到前者别懵这是同一个东西。2.2 报错无法将opencode项识别为 cmdlet、函数、脚本文件或可运行程序的名的完整排查这个报错是 Windows 用户最常遇见的搜索量一度很高。大部分人第一反应是自己没装好其实问题几乎都出在同一个地方npm 全局包的安装目录没有进 PATH。先查 npm 全局包到底装到了哪个目录npm prefix -g正常情况下会输出类似这样的路径C:\Users\你的用户名\AppData\Roaming\npm然后把C:\Users\你的用户名\AppData\Roaming\npm手动添加到系统环境变量 Path 中保存后必须彻底退出终端再重新打开。这里特别强调一下不是新开一个标签页是退出终端进程重开。因为 PATH 环境变量是在进程启动时读取的已经开着的窗口不会自动刷新。还有一个不太容易发现的坑如果你用 nvm-windows 管理多个 Node 版本切换版本后npm 全局包的路径也会跟着变。比如某个 Node 版本对应的全局路径是C:\Users\xxx\AppData\Roaming\nvm\v18.20.0\node_modules但当前终端里 PATH 指向的是另一个 Node 版本目录两个目录对不上命令当然找不到。这种情况下我建议你固定一个常用的 Node 版本或者统一查看当前版本的npm prefix -g路径是否真的在 PATH 里。再往下排查还有一个 Windows 特有的隐蔽情况即便 PATH 配置正确某些安全软件也可能拦截opencode.ps1或opencode.cmd这类的可执行文件。遇到装好了但命令找不到的诡异情况去%AppData%\npm\目录下看看有没有生成opencode.ps1和opencode.cmd文件在不在在的话双击试试能不能运行。2.3 命令能启动了但运行时还有这些幺蛾子能输出版本号之后启动 opencode 还有可能遇到另一个高频问题启动界面刚出现就报一个很宽泛的错误类似unexpected server error让去查 server logs。这类错误十有八九跟网络环境有关。opencode 作为本地服务会监听一个端口来提供交互界面。如果你之前在本机设置过代理环境变量而那个代理程序已经关掉了所有请求都会被代理阻塞界面自然起不来。排查命令$env:HTTP_PROXY $env:HTTPS_PROXY如果这两个变量有值而且指向的是一个已经不存在的代理服务那就取消掉Remove-Item Env:HTTP_PROXY Remove-Item Env:HTTPS_PROXYmacOS/Linux 同理检查 shell 配置文件里有没有相关 export。还有一种误判旧版本升级后没重启终端新老版本进程同时存在端口被占用。这时候把终端里所有 opencode 进程杀掉再重开pkill -f opencode日志文件也是排查利器默认在~/.local/share/opencode/log/打开最新的日志看堆栈比到处搜教程快得多。3. 模型接入和配置把便宜好用的模型用出生产力3.1 先搞懂 provider 体系opencode 的模型接入走的是 AI SDK 生态官方支持 Anthropic、OpenAI、Google Gemini、AWS Bedrock、Azure、Ollama 等一大堆 provider。对我们普通开发者来说最常用到的就两个入口一是官方认证登录二是OpenAI 兼容接口配置。想快速接入官方支持的大厂模型直接用认证命令opencode auth login它会列出可选厂商选一个把 API Key 粘贴进去凭据就存在 opencode 自己的配置目录里了。之后在交互式界面里切换模型不用重复输 Key这个体验很舒服。3.2 配置文件到底怎么写opencode 的配置文件是 JSON 格式默认位置在~/.config/opencode/opencode.json项目目录下也可以放一个.opencode.json项目级配置优先级更高。这个全局 项目双层的设计我很喜欢全局放所有模型和通用偏好项目里只放针对这个仓库的特殊约束。我拿 DeepSeek 为例写一个最小可用配置{ $schema: https://opencode.ai/config.json, provider: { deepseek: { npm: ai-sdk/deepseek, name: DeepSeek, api: { key: env: DEEPSEEK_API_KEY }, models: { deepseek-chat: { name: DeepSeek V3 } } } } }注意api.key用的是env: DEEPSEEK_API_KEY这种写法意思是运行时从环境变量读取密钥而不是把字符串明文写进配置文件。这个习惯我很推荐因为配置文件会交给 git 管理、会在不同电脑间同步明文密钥一旦提交到仓库就是事故。对应设置环境变量export DEEPSEEK_API_KEYsk-你的keyWindows PowerShell 则用setx DEEPSEEK_API_KEY sk-你的key3.3 接入国内可直连的免费或低价模型热搜词里有一条opencode 免费模型说明大家对这块非常关心。我自己试过的国内可直连服务里DeepSeek 的价格压得极低个人开发完全够用智谱 GLM 之前的免费梯度模型在社区讨论度很高但免费版本下线是常态不能指望一个免费档位永久存在像某个 free 模型下线了吗这类话题每隔一阵就会出现。我的建议是把所有能用的 provider 都配置到同一个 opencode 配置里哪个模型的免费额度没了或者质量下降随时切换。这样就不用临时抱佛脚去改配置。以智谱 GLM 为例{ provider: { zhipu: { npm: ai-sdk/zhipu-ai, name: 智谱, api: { key: env: ZHIPU_API_KEY }, models: { glm-4-plus: { name: GLM-4-Plus } } } } }如果你追求完全不花钱可以用 Ollama 跑本地模型。先拉一个编码能力不错的模型ollama pull qwen2.5-coder:14b ollama serve然后在 opencode 里配置 Ollama 作为 provider接口走 OpenAI 兼容{ provider: { ollama: { npm: ai-sdk/ollama, name: Ollama, options: { baseURL: http://localhost:11434/v1 }, models: { qwen2.5-coder:14b: { name: Qwen2.5 Coder 14B } } } } }本地模型在复杂代码推理上确实不如云端大模型但它零成本、私密性好、可离线使用用来做日常的代码阅读、简单重构、单元测试生成完全够用。我个人比较喜欢本地模型的一点是数据完全不出机器写内部项目时心理负担小很多。3.4 不同任务怎么选模型我的一份参考从我这段时间的使用体验来看模型选择不能一套配置走天下任务类型推荐选择理由代码阅读、简单重构DeepSeek-V3、GLM-4-Plus便宜、响应快、够用复杂跨文件推理更强的大模型Anthropic/Gemini上下文理解和多步推理更稳单测生成任意长上下文模型需要跟踪大量已有代码风格完全本地、敏感项目Ollama 本地模型数据不出本机角色扮演调试、解释报错任意快速模型实时性比深度更重要多说一句免费模型不是不能干活而是你必须把任务拆细。让它改好这个模块可能翻车让它先梳理这个模块的调用关系再输出三个需要改的地方会稳很多。这其实不是模型不行是代理式工作本身就需要更清晰的指令颗粒度。4. Agent 机制、Skills 与 Memory它凭什么敢自己干活4.1 Agent 的动手能力边界是怎么设计的opencode 能自己改代码、跑命令遵循的是一个循环式的 agent 机制先分析当前任务和项目状态决定下一个动作读文件、搜索代码、执行终端命令、编辑文件如果动作涉及敏感操作改文件、跑可能影响状态的命令弹出确认列表等你按 y/n/a执行后检查输出决定是继续还是停止这个循环机制的实际意义很大。它不是一股脑把项目权限全拿过去而是把思考和执行拆开你随时可以介入叫停。我用下来最舒服的配置是安全命令如git status、npm test直接放行写文件操作必须确认。为了保证 Agent 不会陷入无限循环opencode 还设置了最大步数限制。新手最容易踩的坑就是不限制步数让一个复杂任务无限跑下去日志刷了几百行还在绕圈。遇到这种情况要么在配置里减少最大步数要么把任务拆得更小。4.2 Skills把团队规范变成 Agent 的行动手册Skills技能是 opencode 一个含金量很高的机制可以把它理解成给 Agent 提供的一套预置行动手册。每份技能包含适用场景描述和具体执行步骤当 Agent 遇到匹配的任务时会自动加载对应的技能包而不是靠用户在对话里手写一大段提示词。我来做一个实战示例。团队经常要做代码审查那我就在全局技能目录里建一个 code-review 技能.config/opencode/skills/code-review/SKILL.md--- name: code-review description: 当用户要求审查代码改动时使用。自动运行 lint、单元测试并检查是否存在过度设计或不必要的破坏性改动。 --- # Code Review 1. 先运行 git diff HEAD~1 查看本次改动范围 2. 运行 npm run lint 与 npm test 3. 逐文件检查 - 是否存在魔法数、硬编码 - 是否有重复逻辑应该抽象 - 是否引入不必要的循环依赖 - 是否存在看似安全实则改变公共 API 的改动 4. 输出审查结论按严重程度排序在这个 markdown 文件里frontmatter 的description字段是触发条件正文是执行步骤。当我在 opencode 里说审查一下最近的代码改动它就会自动加载这个 SKILL.md按照里面的流程执行。技能包的安装非常灵活把别人的技能目录放进~/.config/opencode/skills/就能用。社区里有不少整理好的技能集合比如有人做过 opencode/superpowers 这类增强集里面包含从写 Git 提交信息到前端调试、类型检查的一整套技能包。装好之后 Agent 的行为会明显变得更主动——它会自己先跑工具、收集信息然后给出结论而不是干巴巴地停留在让我看看代码。4.3 Memory让 AI 记住你的习惯和项目演进使用编码代理时最烦的一点是什么是每次新开会话它就失忆了。明明昨天的会话你告诉过它这个项目用 pnpm 不用 npm今天开新对话又忘了。opencode 的 Memory 机制就是为了解决这个问题设计的。它分为两层全局记忆记录你对所有项目的通用偏好存放在用户的本地数据目录下比如提交信息用中文、统一用双引号这类习惯。项目记忆记录某个具体项目的架构决策、关键结论存放位置通常和该项目的 sessions 数据绑定。实测中最有用的还是会话记录。opencode 会把每次会话里你和 AI 的交互、执行动作、最后的结论存储下来。下次开新会话你直接说继续之前的工作它能结合之前的记忆恢复上下文而不是从零开始。如果想让 Agent 稳定遵守项目级公约更可靠的方式还是在项目根目录维护一个AGENTS.md类似 Claude Code 的CLAUDE.md。这个文件每次 Agent 启动任务时都会自动读取项目的潜规则都应该写在这里比如后端项目必须走 Maven profiles 切换测试环境、前端构建必须用 pnpm、某个模块禁止引入新的第三方依赖。写清楚这些比每次对话前补一句记住啊高效得多。我现在的习惯是每个新项目先花十分钟写AGENTS.md后面所有 AI 协作都建立在它之上。这个文件本身也会随项目演进不断更新它既是给 AI 看的指令也是给后来人看的项目笔记一举两得。5. 编辑器插件和桌面版把 Agent 嵌入你原有的工作流5.1 VS Code 插件选中代码直接丢给 Agent很多人习惯了 IDE 内完成所有工作突然切换到纯终端有一些心理门槛。opencode 也提供了 VS Code 插件在扩展市场直接搜 opencode 安装即可。安装后侧边栏会多一个面板你可以选中某段代码右键发送给 opencode它会自动带上当前文件的上下文和相关引用信息。这个模式的体验很好日常写代码还是在熟悉的编辑器里遇到复杂问题需要让 Agent 跨文件排查时再切到 opencode 面板。我个人用下来把在编辑器里选中代码发给 Agent和在终端里直接对话结合起来效率最高。前者适合局部问题的精确定位后者适合全局任务的项目级操作两者互补。5.2 JetBrains IDEA 插件Java/Maven 项目的实战体验经常写 Java 的人可能更关心 IDEA 里的体验。JetBrains 插件市场同样有 opencode 插件我在日常 Maven 项目里用得非常多。最典型的场景是测试失败分析。以前遇到一个单元测试挂了我得自己拿到失败堆栈分析可能是哪行代码的问题再手动去看相关实现。现在直接在 IDEA 的 opencode 面板里说分析一下 UserServiceTest 里 getOrderStatus 测试失败的原因并修复Agent 会自动执行 Maven 测试命令获取真实失败原因再顺着代码定位问题、修改实现、重新跑测试。关键是它拿到的是真实的测试输出而不是靠猜。这里有一个值得特别注意的配置点Agent 执行命令时使用的是终端环境不是 IDE 内部环境。如果你在 IDEA 里能正常跑 Maven终端里却跑不了mvn那 Agent 就会一直失败。遇到这种情况需要在 opencode 配置文件里把 Java 相关的环境变量补上{ env: { JAVA_HOME: C:\\Program Files\\Java\\jdk-17, PATH: C:\\Program Files\\Java\\jdk-17\\bin;%PATH% } }5.3 opencode 桌面版适合长时间挂任务热搜词里的opencode 桌面版是官方出的桌面客户端用 Tauri 写的相当于把终端交互包装进了独立窗口。界面上可以同时看任务列表和文件改动情况比裸终端更直观。我的实际感受是桌面版适合长时间挂着让 Agent 跑的场景。终端版在窗口切换时容易误关桌面版是独立进程就算 IDE 崩了Agent 任务还能继续跑。这也意味着你应该给它一个适合长时间执行的独立任务而不是把它当普通聊天窗口用。5.4 多工具之间的配置切换装了 Claude Code、Codex、opencode 多个终端 Agent 之后一个现实的痛点就来了每家工具的 API Key 和配置文件互不相通。社区里有人做了 ccswitch 这类配置切换工具把各家的 Key 集中管理一键切换当前 CLI 使用的配置。我的建议是不管用什么切换工具至少不要把所有密钥明文存放在同一个容易被同步的目录。opencode 这侧尽量用env:引用系统环境变量这样就算配置文件意外暴露也不会直接泄露密钥。密钥管理这件事再怎么小心都不为过。6. 三个真实场景的实战复盘6.1 接手一个不熟悉项目怎么让 Agent 帮你快速摸清结构接手二手项目是最容易焦虑的场景之一不知道代码在哪、不知道技术栈、不知道构建命令。在 opencode 里我一般先写一份只读委托这是一个前后端分离项目后端用 Maven 构建前端用 pnpm workspace。 请先阅读根目录的 README、AGENTS.md 和 pnpm-workspace.yaml 输出项目结构和技术栈总结。只读不改不要修改任何文件。后面跟上/init指令让它扫描整个项目生成 baseline 说明。之后再问用户注册流程在哪几个文件里它会顺着 controller、service、mapper 一层层找下去。关键点在于一上来必须限制只读权限。让它先摸清结构再动手会避免它在不熟悉代码的情况下乱改。等它把项目结构总结得足够准确再给写权限推进具体任务。6.2 用 Playwright 帮 Agent 定位前端 Bugopencode playwright 怎么测试前端 bug这条热搜很精准地指出了一个高频使用场景。opencode 支持通过 MCP 集成 Playwright让 Agent 真正操作浏览器。我经常让它启动本地前端打开页面点击按钮然后看 console 报错和 Network 请求。配置方式是在 opencode.json 里声明 MCP 工具{ mcp: { playwright: { type: local, command: [npx, playwright/mcplatest], enabled: true } } }配置好之后我可以下达这样的指令用 Playwright 打开 http://localhost:5173/login点击登录按钮 观察 console 是否有报错把报错堆栈抓下来并检查 Network 里登录接口的请求和响应。Agent 会自己完成启动浏览器、操作页面、收集信息、分析结果这一整套流程。这个能力比单纯看代码找 bug 高效得多尤其适合表单校验、登录流程、状态更新这类现象在界面上、根源在代码里的问题。实战中给的建议是复现路径要具体。让它测试登录功能会容易跑偏给它一个具体的 URL、具体点击哪个按钮、关注哪个接口效率和准确性会好很多。6.3 在 Go 和 Java/Maven 项目里各跑一次真实任务先看 Go 项目。我让 opencode 实现一个带内存缓存的 HTTP 接口返回订单状态统计。它直接创建了 main.go、handler、cache 相关文件然后主动执行go build ./...验证编译编译报错也会自动修。最让我印象深刻的是一次go vet报出 interface 断言问题它定位到文件里对应的类型断言修正后重跑测试通过。整个过程我没有写一行代码。Java/Maven 项目也类似。只要命令mvn能在终端正常跑且 pom.xml 在项目根目录Agent 就能通过mvn test获取测试结果并修复单测。我遇到最大的坑其实是环境IDEA 的全局 Maven 设置settings.xml配置了私有仓库地址但终端环境读不到导致 Agent 一开始拉依赖失败。这种情况不属于 Agent 的问题而是环境不一致优先把终端环境配好再让 Agent 干活。6.4 它的短板也藏在这些实战里不能只夸不贬。这段时间我也摸清了它的几个明显短板业务判断是缺失的。当需求涉及领域决策、历史包袱、团队政治因素时AI 会给出看起来很合理的方案但可能不符合真实业务预期。所以它出方案你做决策这个分工很重要。上下文拉长后质量下降。会话太长会影响它的注意力分布一个问题反复追问后它的回复质量会肉眼可见地下降。及时用/compact压缩上下文或者干脆新开会话并引用之前的结论。免费模型在超长代码任务上不稳定。大任务让它先出整体方案和骨架再逐个实现填充比一次性甩给它整个项目的需求要稳得多。一句话总结给够清楚的边界和足够小的任务单元opencode 就是一位非常靠谱的实习工程师放任它自由发挥它也可能在完全错误的道路上走很远你必须在关键节点保持判断力。7. 最后几点个人体会如果我只能分享一条经验那就是从一开始就把AGENTS.md写好并且持续维护它。opencode 每次任务都会读取这个文件项目约定、技术栈、构建方式、目录结构、常见坑都写进去。我之前接手一个项目时花了十五分钟写这个文件之后每个新会话的初始理解成本都大幅降低。它不仅仅是为了 AI也是为了后来接手项目的人。第二点关于免费模型不要迷信任何一个永久免费的模型档位。我见过不止一个模型服务调整政策、下线免费版、更改调用频率限制所以最好的策略是同时配置多个 provider哪个挂了或者不好用了切换成本只是配置里的一个模型名。鸡蛋别放一个篮子里模型也一样。第三点关于升级opencode 迭代非常快建议关注版本更新说明再决定要不要升级。新版本可能会改默认行为、调整配置字段直接升级有时候会碰上旧配置失效的问题。我的习惯是查看 changelog 后才升级不追求第一时间吃螃蟹。最后再分享一个日常工作流技巧每天结束前我会让 opencode 把当天会话里的关键结论追加到项目的 AGENTS.md 里比如发现某个模块存在隐藏依赖这个接口签名建议以后统一。第二天开新会话它就能基于这些记录继续干活不用重新解释上下文。时间长了这个文件就从单纯的给 AI 看的说明书变成了团队的知识沉淀一举两得。opencode 不是银弹它不会让你从不会编程的人一夜之间变成工程师也不会替你做出复杂的业务决策。但对一个已经具备判断力的开发者来说它确实大幅度减少了找代码、跑测试、理调用链这种执行层面的时间消耗让我能把注意力放到更值得关心的问题上。如果你也愿意把 AI 当一个需要带教、需要边界、但执行能力很强的新同事那 opencode 值得你花一个周末来配置和适应。