1. opencode 是什么终端里的开源 AI 编程代理如果你最近关注过 AI 编程工具大概率绕不开 opencode 这个名字。我第一次认真用它是因为当时项目里同时在测 Claude 和 OpenAI 的模型而 Claude Code 对模型锁得比较死Codex CLI 在复杂仓库里的上下文又不够顺手。opencode 是 SST 团队开源的一个本地优先、终端优先的 AI 编程 agent支持 Claude、OpenAI、Gemini也能接 Ollama 这类本地模型以及各种 OpenAI 兼容网关。2.x 版本之后它的会话管理、子代理、技能系统已经能覆盖我绝大多数日常工作。它不是又一个聊天机器人。你在终端里启动 opencode它会先读完你的项目结构再根据你的需求做计划、改文件、跑命令、看测试结果整个过程保留明确的审批节点。换句话说它更像一个坐在你旁边、能自己动手的实习生而不是一个只会在对话框里给你贴代码片段的助手。对于已经用过 Claude Code 或 Codex CLI 的人来说上手成本非常低对于想从 IDE 插件迁移到更自动化工作流的人opencode 也是一个很合适的落脚点。1.1 不是又一个对话机器人而是能自己动手的 agent核心区别在于“行动力”。你在 opencode 里说“把 issue 42 修复掉”它会自己去翻 issue、定位相关代码、改文件、跑测试然后把 diff 摆在你面前。遇到不确定的地方它会停下来问你。这背后是一套基于终端的能力边界读写文件、执行 bash 命令、启动开发服务器、调用 MCP 工具全部通过权限模型控制。我把这种模式理解成“放权但不放养”。一开始我习惯把它的权限设成每步都问后来发现太啰嗦改成默认允许读文件、跑测试但写文件和执行破坏性命令必须确认之后效率才真正上来。opencode 的好处是配置文件就在项目里团队可以约定同一套权限规则而不是靠每个人自己嘴上约束。另外opencode 是开源项目数据默认留在本地。它的会话、配置、技能目录都以普通文件形式存在不依赖某个云账号。这点和很多商业工具完全不同也是它在我这里能长期占一个终端窗口的原因。1.2 它和 Claude Code、Codex CLI、Cursor 的定位差异很多人纠结选哪个。我自己的判断标准很简单看你是不是在意“模型自由”和“工具开放性”。官方工具通常和自家模型配合最顺但如果你想在一套工作流里切换多个模型或者希望记住的 prompt、技能、配置可以被版本管理开源方案会更省心。工具是否开源模型支持交互方式适合场景opencode是多模型、本地模型终端 TUI / IDE 插件想要模型自由、可定制、团队统一配置Claude Code否Anthropic 为主终端深度依赖 Claude 模型生态Codex CLI部分开源OpenAI 为主终端重度使用 OpenAI 模型和 GitHubCursor否多模型图形 IDE喜欢完整 IDE 体验、不介意闭源还有个容易忽略的点社区里新出现的终端 agent 越来越多比如有人会拿 opencode 和pi之类的新工具对比。我的建议是别看宣传直接拿真实仓库试半小时重点看三件事粘贴长上下文后会不会乱、改错文件后能不能救回来、以及技能/MCP 生态是否活跃。工具迭代太快一个项目只要不更新半年后体验就是两个时代。2. 安装、登录与第一次对话opencode 安装本身不复杂但它是一个终端优先工具很多新人的第一道坎反而是“装完打不开”。我在这部分把不同平台的安装方式和第一次配置讲清楚顺便把常见的 PATH 问题一次性说透。2.1 macOS / Linux / Windows 安装官方推荐安装方式是一键脚本。macOS 和 Linux 上我一般用这条命令curl -fsSL https://opencode.ai/install | bash如果你和我一样用 Homebrew也可以走 brew 安装升级会比较方便brew install sst/tap/opencodeWindows 上官方提供了 PowerShell 安装脚本我在自己电脑上实测过新版 Windows Terminal 直接执行就行irm https://opencode.ai/install.ps1 | iex有一点值得单独说opencode 是 Go 写的发布物是单文件二进制没有 Node 运行时依赖所以启动极快。正因为它是个独立二进制升级和卸载都很干净但也正因如此安装脚本默认把二进制放到~/.opencode/bin这种目录能不能直接识别成命令完全取决于 PATH 里有没有这个路径。如果你有 Go 环境也可以go install github.com/sst/opencodelatest我偶尔在容器里用这种方式好处是版本跟得很紧坏处是遇到跨平台编译问题要自己处理。2.2 第一次运行API Key 与模型选择装完之后不要急着对话先把模型供应商配置好。opencode 本身不生产模型它只是一个代理最终调用哪个模型需要你提供 API Key 或本地模型服务。最常见的做法是设置环境变量比如用 Anthropic 的模型export ANTHROPIC_API_KEYsk-ant-...如果你用 OpenAI 兼容的近几十种网关思路一样改成对应的 API Key 环境变量就行。配置好后在项目目录里直接运行opencode它会启动一个全屏 TUI。第一次进来你可以直接输入自然语言任务比如“给我讲讲这个项目怎么跑起来”它会读代码、看文档、列依赖最后给你一份说明。如果你当前的版本支持opencode auth login也可以走账号登录流程但我在团队项目里更推荐环境变量方式因为 CI 和本地可以共用同一套配置换人不换 key。还有个容易被忽略的点opencode 的模型切换非常灵活。你可以在运行时切换也可以在配置文件里指定默认模型。我通常把“快而便宜”的模型作为默认比如处理日志、重构小函数这类任务只有遇到架构级问题时才切到更强的模型。这个习惯帮我省了不少 token也让日常会话速度更快。2.3 安装后立刻遇到的 PATH 问题在 Windows 上最常见的报错是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名这句话的意思是系统在 PATH 里找不到 opencode 这个可执行文件。解决方法分成三步。第一步先确认文件到底装到了哪里where.exe opencode如果提示找不到就去用户目录的.opencode\bin看一下。第二步把这个目录加到用户级 PATH 环境变量。第三步关掉当前终端再重新打开让环境变量刷新。macOS 上如果遇到command not found多半也是同样问题手动把~/.opencode/bin加进 shell 配置文件即可。安装后如果 IDE 插件也提示找不到 opencode不要只重启终端还要重启 IDE。插件启动时读取的环境变量来自父进程终端里的 PATH 不会自动同步到 IDE 里这一点我在 VS Code 和 JetBrains 系里都踩过。3. 配置才是关键模型、套餐、项目级上下文很多人用这类工具只停留在“对话里加 prompt”但真正拉开体验差距的是配置文件。opencode 的项目级配置、全局上下文和记忆机制决定了一个 agent 是像“第一次进仓库的实习生”还是像“跟你合作半年的老同事”。3.1 opencode.json 里该配什么进入项目后我一般先执行opencode init它会生成一个基础配置文件。不同版本字段名略有差异但核心模块是稳定的provider 负责模型供应商permission 负责权限边界mcp 负责外部工具skills 负责技能包。我常用的一个最小配置长这样{ $schema: https://opencode.ai/config.json, provider: { default: anthropic, anthropic: { api_key: env:ANTHROPIC_API_KEY, model: claude-sonnet-4-5 } }, permission: { default: ask, deny: [ bash:git push ] } }这里最关键的是权限配置。我建议新人在头一周把permission.default设成ask让每个重要操作都过一遍你的眼睛。等熟悉了它的行为模式再逐步放开。我在配置里长期保留deny: git push因为 agent 代写提交信息没问题但推送远端这个动作我想保留在可控的流程里。配置文件还有一个大用处可以提交到 Git 仓库。这样团队成员 clone 下来之后不需要各自凑 prompt就能共享同一套模型选择、权限边界和 MCP 工具。团队落地 AI agent配置文件的统一程度直接决定了工具使用规范程度。3.2 AGENTS.md 与 Memory让 agent 记住项目约定opencode 的 Memory 功能我理解成给 agent 开了一个不会忘事的笔记本。但比记忆更稳定的做法是把团队约定写进项目根目录的AGENTS.md。这个文件会被 agent 在启动时读取相当于你每次开会前先给它一份“项目手册”。我通常会在AGENTS.md里写这几类内容# 项目约定 - 测试命令npm test - 禁止直接改动 package-lock.json - 新功能必须补测试 - git 提交信息使用 conventional commit - 修改 API 前先查看 docs/api.md写完之后你会发现 agent 的行为立刻变得“懂规矩”了。它不会再一上来就乱装依赖也不会随便改锁文件。全局性的个人习惯可以放在用户主目录下的全局配置里仓库级的规范放在AGENTS.md一次性任务上下文放在 prompt 里这个三层结构是我用下来最稳的信息组织方式。很多人以为是“模型聪明就够了”其实不是。模型再聪明也不知道你们项目里谁负责哪个目录、测试要用什么命令、历史上有哪些坑。这些信息只有靠AGENTS.md和 Memory 机制持续喂给它模型才能真正从“会写代码”变成“会写你们项目的代码”。3.3 免费模型、本地模型和套餐怎么选先说清楚一件事opencode 工具本身免费但这不意味着调用模型不要钱。官方也提供统一 API 套餐本质是先充值再按 token 结算好处是不用分别管多个厂商的账户一个 key 就能用不同模型。套餐档位和计费倍率会随上游变动我个人的建议是别急着买大额套餐先用消耗低的模型跑两天看你的实际使用量再决定。社区里经常有人分享“免费模型通道”比如之前传过一阵的 hy3-free 之类的名字。我的态度比较保守免费通道适合拿来玩、做 demo、验证流程不适合放生产环境。因为这类通道上下线频繁经常排队稳定性完全取决于维护者的心情。你正在改一个紧急 bug结果模型 provider 挂了这种体验一次就够受的。本地模型是另一个方向。如果你有 Ollama只需要在 opencode 里配一个 OpenAI 兼容的本地服务地址{ provider: { ollama: { url: http://localhost:11434/v1, model: qwen3-coder } } }本地模型的好处是隐私和数据安全成本也低但代码生成质量和中大规模仓库的理解能力跟顶级商用模型比还有差距。我现在的分工是本地模型处理日志分析、批量文本改写、简单脚本商用模型处理架构设计、复杂测试、跨模块重构。这种组合既省钱又不牺牲质量。3.4 用 cc-switch 这类工具管理多套配置用 opencode 越久你会发现自己手上的配置越多家用电脑一套、公司项目一套、客户环境一套每套可能要配不同的 API Key、模型和权限策略。手动去改 JSON 文件很容易出错尤其是多台设备之间同步时漏改一个字段就会导致 agent 行为偏离预期。cc-switch 这类工具解决的就是这个问题。它提供了一个图形化或命令行的配置切换界面把 opencode、Claude Code、Codex 等工具的配置集中管理起来。你可以在里面保存多份 profile按项目一键切换。尤其是命令行版或者说“opencode go”这种偏 nerd 的用法没有图形面板辅助时配合 cc-switch 这类工具能省下大量改配置的体力活。我的习惯是项目级配置入库全局密钥不入库。目录里放一个opencode.json里面的 key 用env:方式引用环境变量cc-switch 负责管理不同场景的全局 profile把对应的环境变量或配置片段切到当前 shell。这样即使配置切换出错也不会把密钥真正泄露到 Git 里。4. 进阶玩法Skills、MCP 与前端 bug 排查配置文件打好底子之后接下来就是 opencode 真正值钱的地方技能系统和外部工具接入。这两样东西让 agent 从“通用程序员”变成“懂你项目流程的专用助手”。4.1 Skills 和 superpowers 插件包Skills 可以理解成给 agent 预装的“工作模板”。比如你经常做 UI 走查就写一个ui-review技能里面规定好要看哪些页面、检查哪些指标、用什么输出格式。以后每次只要说“用 ui-review 看一眼登录页”它就会自动按流程走不用你每次重复描述需求。技能包本质上是一组目录和 markdown 文件。常见的结构大致是~/.config/opencode/skills/ui-review/ ├── SKILL.md ├── system.md └── prompt.mdSKILL.md是入口说明system.md是给模型的系统指令prompt.md是用户侧会看到的提示词模板。我一开始觉得写技能很麻烦后来发现这跟写测试用例一样投入一次长期受益。社区里很多人提到的 superpowers就是一套成熟的 skills 合集覆盖代码审查、重构、前端调试等场景。如果你以前用过 oh-my-claudecode 这类配置包会发现很多 prompt 思路可以平移到 opencode。安装时留意一件事技能目录的扫描路径在不同版本里可能不一样clone 完先看一下当前版本实际读取哪个目录别装完发现没生效。4.2 接 Playwright 测前端 bug用 opencode 做前端开发时最大的痛点是它看不到界面。解决思路有两种一种是让它直接跑 Playwright 脚本另一种是接 MCP 浏览器工具。我更推荐后者因为交互更自然你可以直接说“打开页面点那个按钮看 console 报错”。在opencode.json里加一个 Playwright MCP 服务{ mcp: { playwright: { command: npx, args: [playwright/mcplatest] } } }重启 opencode 之后你就能在对话里让它用浏览器操作页面。我经常这样描述 bug“用 Playwright 打开 localhost:5173进入设置页勾选两个选项然后提交。复现一下这个场景里的报错把 console 和 network 里的失败请求列出来。”它会自己启动浏览器、执行操作、收集信息然后结合代码定位问题。这里有个很实用的排查技巧如果 Playwright 启动浏览器失败先检查是不是没有安装 Chromium直接让 agent 运行npx playwright install chromium。如果页面需要登录态可以先把登录后的 cookie 文件路径告诉它或者提前用playwright codegen录制一条稳定路径避免每次都卡在登录上。4.3 用 subagent 提效的思路opencode 里可以开多个子 agent我把它当成“分工”来用。一个 agent 专门看日志、整理报错另一个 agent 同时去改代码。主 agent 负责调度最后把两个结果合并。这个模式特别适合定位跨模块 bug比如前端报错、后端异常、数据库数据不一致同时出现的情况。但别一上来就开一堆 subagent。context 有限信息窗口会被撑爆。我常用的做法是先让一个 agent 把问题收敛到具体文件和函数再针对这个范围派第二个 agent 去做修改。范围越小子 agent 的效果越明显一上来就给一个十万行仓库让它自由探索反而容易跑偏。5. 日常实操从接手项目到提交代码配置和技能都齐了之后日常开发就变成一个“如何把需求清晰描述出来”的问题。这里分享一些我在真实项目里反复使用的流程和注意点。5.1 一句话开始一个务实任务我不会把 opencode 当成无所不能的架构师而是把它当成一个“行动力很强的执行者”。所以我给它任务时会刻意写清楚目标、边界和验证方式。比如opencode 修复登录页在移动端点击登录按钮无响应的问题。先看一下最近的 console 报错定位到具体组件修复后跑一遍现有的登录相关测试。这个 prompt 包含了目标、线索、动作范围和验证条件。对比一下“帮我修个 bug”这种模糊说法效率差距非常大。更进阶的做法是让 agent 自己建分支、改代码、跑测试、生成提交说明最后把分支 push 到远端。当然push 这一步我通常手动执行因为我要在 push 前看一遍 diff。还有个小技巧如果项目很大先问它“这个项目的目录结构是怎么组织的”等它读完再给任务。这样相当于先让 agent 建立心智地图后续改代码会准确很多。直接甩一个任务进去它往往会在无关目录里浪费时间。5.2 Java / Maven 项目里的注意点Java 项目里跑 opencode最常遇到的问题不是模型而是构建环境。假如你的项目用 Maven但本机没配JAVA_HOMEagent 执行mvn test就会失败它会带着一脸问号反复重试。所以我在项目根目录的AGENTS.md里会特别写清楚- Java 版本要求17 - 构建命令./mvnw clean test - JAVA_HOME 位置/opt/jdk-17用./mvnw而不是裸mvn是个好习惯。Maven Wrapper 会把构建环境固定下来agent 执行的时候不会因为你本机装了不同版本的 Maven 而行为异常。如果你确实需要让 agent 直接用 mvn那就确保mvn -v在任何一个新开的终端里都能正常运行否则 IDE 插件里启动的 agent 可能继承不到环境变量。Java 项目还有一个特点编译慢。如果每次都让 agent 全量编译成本很高。我一般让它用-pl指定模块或者先mvn compile -DskipTests快速验证语法再在关键节点跑完整测试。这个思路同样适用于大型前端 monorepo先用tsc --noEmit做类型检查再跑具体测试文件。5.3 VS Code / JetBrains 插件怎么配合opencode 的终端 TUI 体验已经很完整但大部分人还是习惯在 IDE 里看 diff。VS Code 插件和 JetBrains 插件我都试过工作方式其实很像安装扩展后选择本机的 opencode 二进制路径然后在侧边栏或面板里打开项目就能直接开始对话。IDE 插件最大的优势是 diff 视图。agent 改完代码之后你能像 review 同事代码一样逐行看变更该撤回的撤回该保留的保留。相比之下终端里看 diff 虽然也支持但遇到跨多文件的改动体验还是不如 IDE 直观。关于“桌面版”我看到过一些社区封装也有官方方向的尝试。我的看法是桌面版和 IDE 插件本质都是给同一个 opencode 核心套了一层壳最终读的还是同一份配置和会话目录。所以不用纠结用哪个入口核心能力都在底层。我现在的主力组合是终端里跑 TUI 处理复杂任务IDE 插件负责 diff review 和小范围修改。6. 高频问题与避坑实录最后这部分是我实际使用中踩过的坑以及经常在社区里看到的问题。整理成一张速查表再分享几个长期省心的习惯。6.1 常见报错速查表报错或现象常见原因解决办法无法将“opencode”项识别为 cmdletPATH 未包含 opencode 目录用where.exe opencode定位加入用户 PATH 后重启终端unexpected server error. check server logs模型供应商服务端异常或密钥失效先看 API 余额和 Key再等待后重试检查服务状态页模型名称找不到provider 不支持该模型或版本过旧opencode升级或查当前 provider 的模型列表MCP server failedPlaywright 等 MCP 工具未安装依赖手动跑一次命令安装 Chromium检查端口冲突mvn command not foundJAVA_HOME 或 Maven 环境未配置使用./mvnw或在 AGENTS.md 写清路径agent 长时间不干活权限设置过严或提示词太模糊给更明确的任务范围适当放开只读命令权限这里想单独说一句unexpected server error。我见过不少人在群里焦虑以为是 opencode 坏了其实绝大多数时候是上游 API 服务抖动或者某个免费通道下线了。排错顺序应该是先换一个模型测试如果其他模型正常说明是原模型供应商的问题如果所有模型都报错再检查本地配置和网络连接。别一上来就重装工具浪费时间。6.2 我用 opencode 半年后想告诉你的几件事第一权限配置一定要先收紧再放开。新手最容易犯的错误是图省事把权限设成“全自动”结果 agent 在你没注意的时候跑了一堆破坏性命令。我见过最夸张的一次是它把整个node_modules删掉重装虽然理论上没错但那个等待时间真的很疼。正确做法是先全 ask跑一周再根据实际需要逐步放权。第二AGENTS.md值得花时间认真写。很多人觉得这是额外负担但你写一次后面所有会话都在复用。尤其是团队协作时一个结构良好的项目说明文件能让每个成员用 agent 的体验都稳定在同一水平线上。反过来如果每个人各写各的 prompt结果就是十个 agent 有十种开发风格团队 review 成本直接上升。第三不要让免费模型承担核心生产任务。免费通道适合测试和体验一旦项目进入交付阶段稳定的付费模型是值得投入的成本。我之前接过一个需求用一个免费通道跑了三天每天掉线两次后来算下来浪费的时间早就超过了那点 token 费用。第四每次让 agent 做完修改至少自己读一遍 diff。这不是不信任而是在建立对工具行为的直觉。读 diff 时你会慢慢发现它擅长什么、容易在哪类问题上犯错后面给 prompt 时就知道该重点强调什么。工具用得好的团队都是先对人负责再对工具放权。