如果你最近刷开发者社区大概率会看到 opencode 这个名字反复出现搜索热度从安装、使用教程一路延伸到免费模型、桌面版、是哪家公司的甚至还有一串经典的 Windows 报错在到处被转发。我大概在它 2.0 用 Go 重写之后才真正把它放进日常工具链启动速度和响应体感确实让我把用了两个月的 Codex 晾在了一边。这篇文章不打算复读官方文档而是把我从安装、接模型、写配置、接入 IDE到排查各种报错的完整过程记录下来给想上手 opencode 的人一份能直接照着操作的标准使用指南。无论你是刚听说这个工具还是已经装好但卡在配置环节应该都能从里面找到对得上的那一节。1. opencode 到底是什么SST 团队的开源 AI 编程代理凭什么冲上热搜1.1 一句话定位终端里的 AI 结对程序员opencode 是一个开源的终端 AI 编程代理AI Coding Agent代码托管在 GitHub使用 MIT 协议。很多人第一次搜索opencode 是哪家公司的得到的答案其实挺反直觉——它不来自任何互联网大厂而是由 SST 团队开发就是做 SST serverless 框架那个团队。这个背景很重要因为它决定了 opencode 的很多设计取向底层偏工程化、重插件生态、对开源集成非常友好而不是那种某个大厂为了绑定自家云服务而做的封闭工具。它的核心工作方式很简单在终端里启动一个交互式 TUI 界面你用自然语言描述需求它作为代理去读取项目代码、执行 shell 命令、读写文件、跑测试而不是像传统 AI 补全那样只在你光标后面接几行代码。这一点和 Claude Code、Codex 是同一类产品但 opencode 从一开始就把模型无关作为原则——不要求你必须用某一家的大模型。我用一个类比来解释它在工作流中的位置如果说 GitHub Copilot 是自动补全的输入法那 opencode 就是一个坐在你旁边、能自己动手翻代码、敲命令、改文件、跑测试的实习生你只需要把活儿说清楚然后 review 它干完的活。1.2 关键特性盘点多模型、Skills、Memory、MCP、LSP我用了这段时间之后觉得这几个特性是它和其他终端 Agent 拉开差距的核心多模型接入Anthropic Claude、OpenAI GPT、Google Gemini、Groq 都可以接还支持 OpenRouter 聚合和 Ollama 本地模型。这意味着你可以根据任务难度切换模型省钱和效果两头抓。Skills 技能系统通过 Markdown 格式的技能包告诉 AI 在特定场景下按什么流程干活等于给 Agent 装操作手册后面我会详细讲。Memory 持久记忆它能把项目偏好、技术栈约束、用户习惯写到本地记忆里跨会话保留。MCP 支持可以接入各种 MCP Server比如数据库、浏览器、文件系统、Playwright 等外部工具。LSP 集成利用语言服务器协议读取代码库的符号、引用、定义对大型项目的理解能力明显强于纯文本塞上下文的实现。这套组合拳打下来它的定位就不再是聊天窗口 终端而是一个可以长期参与项目维护的工程协作实体。1.3 从 TypeScript 到 Go2.0 重写背后的性能逻辑opencode go这个热搜词我猜指的就是 2.0 的 Go 重写。旧版用 TypeScript/Node 实现功能没问题但启动延迟和流式响应都有点重。2.0 用 Go 重写整个引擎之后启动时间降到几百毫秒级别内存占用也明显下降。为什么性能在这种工具里这么敏感因为 Agent 的工作模式是高频小步迭代——每次工具调用、每次文件读取、每次流式 token 输出都有固定开销。如果一个操作要等几百毫秒才出结果你连续看十次就会烦躁如果每次循环都快整个体验就完全不一样了。我自己的体感是Go 重写之后的 opencode 在长任务里的手速明显更接近真人结对编程的节奏这直接影响我愿不愿意把它用在复杂重构场景里。提示如果你之前安装过旧版 Node 版本升级到 2.0 后建议把旧的全局包卸掉避免两个二进制在 PATH 里打架。这个坑我后面踩坑章节会展开。2. 安装全流程Windows / macOS / Linux 三种方式与首次启动2.1 三种安装方式怎么选opencode 官方推荐的安装方式有这么几种我列个表直接对比安装方式命令适用场景官方脚本curl -fsSL https://opencode.ai/install | bashmacOS / Linux 最快上手npm 全局安装npm install -g opencode-ai已装 Node 生态、方便统一管理Homebrewbrew install sst/tap/opencodemacOS 用户习惯 brew 管理Go 安装go install github.com/sst/opencode/cmd/opencodelatest已经用 Go、想要最新构建手动下载GitHub Releases 下载对应平台二进制Windows 或内网环境我个人的建议是macOS 用户直接 brewLinux 用户用官方脚本Windows 用户优先用 WSL或者直接装桌面版。如果你不想折腾npm 全局安装是兼容性最好的但要注意 npm 全局 bin 目录的 PATH 问题这正是后面那个报错的来源。2.2 首次启动登录鉴权与模型选择装好之后在终端运行opencode第一次启动会进入配置引导它会检测你系统里的环境变量比如ANTHROPIC_API_KEY、OPENAI_API_KEY如果检测到就直接可用没有的话会提示你执行opencode auth login这个命令会自动打开浏览器按提示走一次授权流程。当然如果你不想走交互登录也可以直接在 shell 配置文件里导出 API Key相当于手动注入凭据。进入 TUI 之后第一件事是选择模型。我建议用/models命令打开模型列表这里面会展示当前已配置 provider 下的所有可用模型。如果列表为空说明你的 provider 还没配好回到下一章继续看。初次上手我推荐先用一个够用但不贵的模型跑通流程比如 Claude Sonnet 系列或 GPT 系列的中端型号不要一上来就用最贵的 Opus因为 Agent 场景一个任务会产生大量 token费用涨得比你想象快。2.3 Windows 下无法将 opencode 识别为 cmdlet的根因与解法热搜里那条opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名是所有 Windows 新手最容易撞上的报错。它的本质很简单Windows 在 PATH 环境变量里找不到名为 opencode 的可执行文件。如果你用的是 npm 全局安装先查一下 npm 的全局 bin 目录在哪npm prefix -g正常情况下输出类似C:\Users\你的用户名\AppData\Roaming\npm。然后检查这个路径是否在 PATH 环境变量里打开系统属性 - 环境变量在 Path 里添加这一行保存后重新打开一个终端窗口——注意是重新打开不是继续用旧窗口因为环境变量只在进程启动时读取一次。如果你用的是官方脚本或手动下载的二进制确认一下下载的文件路径把它所在目录同样加进 PATH。还有一个更省事的选择直接安装 opencode Desktop 桌面版绕开终端环境变量这堆事。注意如果之前安装过旧版先执行npm uninstall -g opencode-ai或删除旧二进制再装新版。两个版本共存会让 PATH 里出现旧版本优先的问题到时候你会排查半天。3. 模型接入与配置官方 API、OpenRouter、免费模型到底怎么配3.1 官方模型接入Anthropic 与 OpenAI 的直连先说不绕弯的。你要用 Claude就要有ANTHROPIC_API_KEY要用 GPT就要有OPENAI_API_KEY。在 shell 配置里导出就行export ANTHROPIC_API_KEYsk-ant-... export OPENAI_API_KEYsk-...Windows 上对应的是setx ANTHROPIC_API_KEY ...或者直接在系统环境变量里加。然后重启 opencode用/models就能看到对应模型。直连的优点是延迟低、稳定、官方 SDK 适配最好缺点是贵而且 key 管理要注意安全。我一般只在需要最强模型处理复杂任务时才切到 Opus 或最顶级的 GPT 型号常规编码用中端型号就够了。3.2 用 OpenRouter 聚合多家模型一个 Key 走天下OpenRouter 是我最常用的接入方式它解决了一个很实际的痛点不同任务想用不同模型但不想每个平台都去申请 key。OpenRouter 提供一个统一 API你只需要一个 key 就能访问它平台上的所有模型。在 opencode 里配置 OpenRouter步骤很简单去 OpenRouter 官网申请 API Key导出环境变量OPENROUTER_API_KEY。打开 opencode 模型列表选择 provider 为 openrouter。在模型列表里挑具体型号比如anthropic/claude-sonnet-4、openai/gpt-5等。在 TUI 里你可以随时用/models切换模型不用重启进程。这一点在 Agent 场景里太好用了——先用便宜模型做批量改动遇到复杂重构再切到强模型成本可控。3.3 免费/低成本方案Ollama 本地模型与 OpenRouter 免费档opencode 免费模型这个热搜我猜大家都想知道怎么白嫖。目前靠谱的路径有两条一条是本地模型一条是 OpenRouter 的 free 模型档。先讲本地模型。如果你机器内存够大32G 以上跑 Ollama 是零成本方案。安装 Ollama 后拉一个编码模型ollama pull qwen2.5-coder:32b ollama serve然后在 opencode 里选择 provider 为ollama就能看到本地模型列表。本地模型的好处是隐私好、无 API 费用、离线可用坏处是代码生成质量跟顶级云端模型还是有差距更适合完成结构性明确的机械任务比如补测试、写正则、批量改格式。再讲 OpenRouter 免费档。OpenRouter 上有一部分标着free的模型用它们不扣额度但稳定性一般。我实测下来免费模型经常会在长任务中途超时或限流所以我的建议是可以拿来体验和低强度任务但别拿它跑重要生产级任务。3.4 opencode.json 配置字段拆解项目级和全局级优先级opencode 的配置采用 JSON 文件全局配置在~/.config/opencode/opencode.json项目级配置在你的项目根目录opencode.json。两个文件可以同时存在项目级配置会覆盖全局配置的对应字段。一个最小可用的配置长这样{ $schema: https://opencode.ai/config.json, provider: openrouter, model: anthropic/claude-sonnet-4, agent: build, permissions: { read: true, write: true, run: [node, npm, git, go, mvn] } }字段说明$schema编辑器智能提示用推荐保留。provider默认的模型提供商。model默认模型。agent默认使用的 Agent 模式。permissions控制 Agent 能读取、写入和运行的命令白名单。这个字段非常实用限制到白名单之后能防止 AI 在执行任务时乱跑命令。关于权限配置我有一个血的教训早期我把run设成了true放开所有命令结果有一次它为了修复一个权限问题直接对我的 git 配置下了手虽然不是破坏性操作但确实折腾了我好一阵。后来我改成白名单制只在有明确需要时才临时放开某个命令安全性和可控性都好了很多。4. 实战工作流从帮我写个函数到接手整个项目4.1 基础交互斜杠命令、Agent 模式与 Plan 模式安装配置完成后的第一件事是熟悉 TUI 的基本操作。opencode 的交互主界面由对话区、输入框和状态栏组成最常用的斜杠命令有这么几个命令作用/models切换模型/agents切换 Agent 模式build / plan / custom/skills启用或查看技能/memory查看和管理持久记忆/help查看全部命令我强烈建议你养成一个习惯大改动先切到 plan 模式。plan 模式下 Agent 不会直接改代码而是先读代码、分析方案、输出计划等你确认后再执行。对于重构某个模块迁移数据库字段这种任务plan 模式能避免 AI 一头扎进去改出一堆你不想看到的中间态。确认计划没问题之后再切回 build 模式让它真正动手。4.2 skills 技能包用 superpowers 规范 Agent 行为opencode skills和opencode 安装 superpowers这两个热搜一起看就懂了——skills 是 opencode 的灵魂之一。一个 skill 本质上是一份 Markdown 指南它告诉 AI 在特定场景下应该遵循什么步骤、注意什么边界。没有 skills 的 Agent 像一个有潜力但缺乏经验的开发者有了 skills 之后它才像手边摆着团队规范文档的老手。社区里很火的一套技能包是 superpowers也就是 Jesse Vincent 开源的那套 skills 集合由一系列可组合的技能组成从如何拆分任务到如何做 TDD 调试都有。安装方式是把技能包克隆到 opencode 的技能目录git clone https://github.com/obra/superpowers.git ~/.config/opencode/skills/public/superpowers装好后在 opencode 里运行/skills就能看到并启用。我实际用过之后最大的感受是启用 superpowers 里的 debug 技能后AI 面对一个诡异的 bug 不会再猜一个改法试一下而是会按先复现 - 二分定位 - 打日志 - 验证修复的流程走明显更靠谱。4.3 memory 记忆让 Agent 记住你的项目偏好memory 是 opencode 比较有特色的功能。它可以把项目相关信息——比如这个项目用 pnpm 不用 npm接口返回统一包一层 data 字段测试文件必须放在tests目录——持久化保存之后所有会话都能读取。你可以在对话里直接让 AI记住某个规则它会自动写入 memory也可以主动编辑记忆文件。我带新项目的时候第一件事就是把项目约定写进 memory后面所有 Agent 会话都会遵守这些约定省去反复强调的沟通成本。不过 memory 也要注意污染问题。我踩过的坑是让 AI 记住了一个只针对某个临时分支的规则结果其他项目也读到了产生了一些莫名其妙的“符合规范”的改动。所以项目特殊的规则尽量放在项目级配置或项目级 memory 里别放到全局。4.4 用 opencode 接手存量项目的正确姿势opencode 接手开发项目这个场景我觉得是它最实用的地方。拿到一个从没见过的代码库过去我会花大半天读文档、理目录结构现在我会让 opencode 先帮我做一次代码库侦察。我会这样下指令这是我从没接触过的项目。请先分析项目结构、核心模块和技术栈输出一份项目概览包括主要目录职责、关键入口文件、数据流方向、构建测试命令。不要修改任何代码。由于 opencode 自带 LSP 能力它能真正读取代码符号和引用关系而不是只做关键词匹配。过几分钟我就能得到一份相当靠谱的项目结构说明比人肉翻代码快得多。然后我会让它基于这份概览去实现一个小需求通过这个小需求验证它对项目的理解是否准确——如果理解有偏差就当场纠正把正确理解写进 memory。这个流程走下来接手一个中型项目的时间和切换成本明显下降。4.5 用 Playwright 测试前端 bug从复现到回归的一条龙opencode playwright 怎么测试前端 bug这段时间问的人很多我分享一下自己的用法。opencode 通过 MCP 接入 Playwright 之后可以把浏览器操作能力交给 Agent让它像人一样打开页面、点击、输入、截图。实际的 debug 流程是我把 bug 描述给它比如登录页在移动端视口下验证码按钮被遮挡点击无效然后让它用 Playwright 打开本地开发服务器设定移动端视口复现问题并截图。它会把截图路径返回给你你一看就知道问题是不是真的存在。定位到问题后它再回到代码里修复修复完再用 Playwright 跑一遍同样的操作验证。这个工作流的价值在于闭环传统的 AI 修复全凭文本理解经常修了 A 坏了 B而有了 Playwright 的验证环节Agent 能自己确认修复是否有效。我实际用下来前端 bug 的一次修复成功率明显提升。5. 编辑器与桌面端集成VSCode、JetBrains 与 Desktop 的适用场景5.1 VSCode 插件在编辑器里直接使用 opencode如果你主要用 VSCode从扩展市场搜opencode安装官方插件即可。装完之后侧边栏会出现 opencode 面板你可以在编辑器里直接对话它会读取当前打开的代码选区作为上下文回复里的代码还支持高亮和直接插入文件。用插件的好处是不用在终端和编辑器之间来回切换。我个人的工作流是简单问题直接在 VSCode 侧边栏问复杂重构回到终端 TUI 里操作。而且两者共享同一套配置和 memory切换成本很低。有个使用细节建议在 VSCode 插件里如果 Agent 要跑前端项目最好让它调用集成终端而不是普通调试终端否则有些 dev server 的输出捕获不到。5.2 JetBrains IDEA 插件与 Maven 项目注意点JetBrains 系的插件在 IDEA 插件市场里同样能搜到。安装后会在右侧工具窗口出现 opencode 面板操作逻辑和 VSCode 版类似。Java/Maven 项目有一些额外的注意事项这也对得上opencode mvn配置这个热搜。首先是确保 PATH 里能找到mvn命令IDEA 内置的 Maven 路径和终端 PATH 不一定一致。opencode 执行 shell 命令时用的是系统环境变量所以要在系统层面把 Maven 配好而不是只在 IDEA 里配。其次如果项目用了多模块 Maven 结构建议让 opencode 优先使用mvn -pl 模块名 test这样精准的命令而不是mvn test否则它每次验证都要全量构建慢得让人着急。我一般会在项目级配置的 permissions 里把 mvn 加入白名单同时把常用的模块构建命令写进 memory。5.3 Desktop 桌面版适合什么场景opencode 桌面版也是热搜词之一。Desktop 版是独立图形界面把终端 TUI 搬到了原生应用里配置、模型切换、skills 管理都做了可视化。我的体验是Desktop 适合两类场景。一类是 Windows 用户——它能绕开 PowerShell 那些环境变量和编码问题开箱即用另一类是多项目切换频繁的使用者——Desktop 的项目管理界面比终端更直观可以同时挂多个项目的会话。不过如果你已经习惯了终端 TUI 的效率操作Desktop 并不带来额外的能力只是换个壳。我的建议是新用户从 Desktop 入门降低门槛老用户回到终端提高效率两者共用配置不冲突。6. 踩坑实录从安装到实战的高频报错与完整排查链路6.1 error: unexpected server error 的完整排查过程热搜里那句c:\windows\system32opencode error: unexpected server error. check server lo...我太熟了也踩过不止一次。这个报错的特点是信息量极少根本没有告诉你哪一层出了问题。所以排查需要按链路一步步来看日志opencode 的日志通常在~/.local/share/opencode/log目录macOS/Linux或对应用户目录的 AppData 下。先看日志找更具体的错误信息。排除配置问题检查当前选的 provider 是否真的配置了有效 API Key可以先用 curl 直接请求 API 确认 key 和网络没问题。检查网络环境如果你的环境有代理或防火墙API 请求可能超时。这个需要在系统层面处理我不展开。确认模型名是否有效有时候 OpenRouter 上的模型会下架或改名而你的配置里还留着旧模型名。opencode 会返回 unexpected server error实际是模型不存在。解决办法是用/models重新选择有效模型。重启进程如果以上都排除了直接退出重开。opencode 2.0 的守护进程偶尔会进入异常状态重启能解决大部分莫名奇妙的报错。排查的顺序之所以重要是因为很多人一看到报错就重装浪费时间。先日志、再配置、再网络这个顺序能覆盖绝大多数情况。6.2 ccswitch 配置后不生效优先级问题ccswitch配置opencode这个热搜指向的是不少人在用的模型/provider 切换工具。它可以集中管理多个服务商的配置一键切换。但有个高频问题在 ccswitch 里切了之后opencode 里没变化。根因多半是配置读取优先级。opencode 会按项目级配置 全局配置 环境变量 外部工具写入的配置的顺序读取ccswitch 如果写的是它自己的全局变量但 opencode 项目级配置文件里显式指定了另一个 provider那自然是项目配置赢。排查链路先看项目根目录有没有opencode.json有的话先确认它的 provider 和模型字段再看全局配置~/.config/opencode/opencode.json最后确认环境变量有没有导出冲突的 key。改完之后一定记得退出 opencode 进程再重开配置只在启动时读取。6.3 免费的 hy3-free 模型下线第三方免费端点的脆弱性opencode hy3-free 下线了吗这个问题答案是确实说过就过。社区里出现过一些第三方免费模型端点打着免费高速的旗号被用来接入各种 Agent。这些端点最大的问题就是不稳定——要么突然限速要么直接关停而且你无法确认请求的数据被谁看到了。我的态度很明确免费端点可以尝鲜不要依赖。真正的生产力场景要么用官方 API 走量控制成本要么用本地 Ollama 零成本跑私有任务。把核心项目依赖在一个随时可能消失的第三方免费服务上是给自己埋雷。6.4 oh-my-claudecode 与 opencode 混用时的 PowerShell 冲突oh-my-claudecode 是一套给 Windows PowerShell 用的脚本集很多人装它是为了在 PowerShell 里舒服地使用 Claude Code 等工具其中会注册一堆 alias 和函数。问题就出在这里这些自定义函数里如果有覆盖opencode的包装逻辑PowerShell 在解析命令时函数优先级高于 PATH 中的可执行文件于是你运行的opencode其实是脚本里的旧包装函数行为就会很诡异。排查方法很简单执行Get-Command opencode -All如果输出里列出了函数Function 类型就说明被覆盖了。解决办法是直接调用完整路径绕过 alias或者把 oh-my-claudecode 的包装函数改名避免冲突。6.5 配置文件的坑字段冲突与覆盖关系最后一类坑集中在配置本身。permissions.run如果设置了命令白名单你又想让 Agent 执行某个不在白名单里的命令它会失败。这时候不要直接改配置成true更稳妥的做法是把那个命令加进白名单数组。再有一个常见的坑是项目级配置里的 model 字段你明明在/models里切到了 A 模型但重新打开后它又回到配置里的 B 模型。这是因为/models的切换是临时的不写回配置文件。想让默认模型固定下来就去项目级配置改model字段。7. 横向对比与选型建议opencode、Codex、Claude Code、Pi 怎么选7.1 四款工具的核心定位差异最近opencode codex claude code哪个 agent 好用这类对比特别多社区里还有把 Codex、Claude Code、Pi 和 opencode 放在一起比的。它们表面都是终端 Agent但骨子里的定位差异很大。Claude Code模型能力最强的官方终端 Agent深度绑定 Claude 系列交互设计打磨得非常好适合就想用最强模型 不差钱的用户。CodexOpenAI 的终端 Agent和 GPT 系列模型绑定和 GitHub 生态结合好但相对封闭扩展性弱一些。Pi这个是近期讨论度逐步上来的新竞争者同样主打终端交互但生态成熟度还在早期我在实际项目里没有大规模使用暂时作为观察对象。opencode最大的差异点是模型无关 完全开源 扩展生态丰富。它把模型层抽象得很好Anthropic、OpenAI、本地模型、聚合平台都能接而且 skills/memory/MCP 的开放程度是目前这几个里最高的。7.2 实测对比表我根据自己连续几周的实际使用做了一张主观但诚实的对比表对比维度opencodeClaude CodeCodexPi模型自由度高支持多家本地低绑定 Claude低绑定 OpenAI中等开源程度完全开源MIT闭源闭源部分开源启动性能Go 重写后快中等中等中等Skills/Memory 生态丰富、开放有 Skills 但封闭较弱早期IDE 集成VSCode JetBrains 桌面版插件依赖官方VSCode 插件较少上手门槛中等配置项多低低低长任务稳定性高实际体验高中等中等7.3 我的选择和理由如果你是完全的新手急着上手我会推荐 Claude Code它的官方开箱体验最平滑但如果你和我一样希望用一个工具对接多个模型、本地跑私有任务、并且能深度定制 Agent 行为opencode 是更值得投入的那个。我的最终选择是 opencode 作为主工作流保留 Claude Code 作为特定场景备选。原因很简单我把团队项目的短期需求都写在项目级配置和 memory 里无论底层模型是 Anthropic 还是 OpenAI 还是本地模型opencode 的交互层和技能层是稳定的。这种底层模型可以换工作流不塌的特性才是它最打动我的地方。最后再分享一个实际经验不管用哪个 Agent把它当成一个能力很强但没有项目经验的协作者而不是一个全知全能的神。在关键操作前让它先说计划在它动手后认真 review diff把这套流程固化成习惯你才能真正享受 AI 编程代理带来的效率提升而不是被它制造的新问题折腾得焦头烂额。 opencode AI 编程代理从入门到实战：安装、模型接入与踩坑全指南
如果你最近刷开发者社区大概率会看到 opencode 这个名字反复出现搜索热度从安装、使用教程一路延伸到免费模型、桌面版、是哪家公司的甚至还有一串经典的 Windows 报错在到处被转发。我大概在它 2.0 用 Go 重写之后才真正把它放进日常工具链启动速度和响应体感确实让我把用了两个月的 Codex 晾在了一边。这篇文章不打算复读官方文档而是把我从安装、接模型、写配置、接入 IDE到排查各种报错的完整过程记录下来给想上手 opencode 的人一份能直接照着操作的标准使用指南。无论你是刚听说这个工具还是已经装好但卡在配置环节应该都能从里面找到对得上的那一节。1. opencode 到底是什么SST 团队的开源 AI 编程代理凭什么冲上热搜1.1 一句话定位终端里的 AI 结对程序员opencode 是一个开源的终端 AI 编程代理AI Coding Agent代码托管在 GitHub使用 MIT 协议。很多人第一次搜索opencode 是哪家公司的得到的答案其实挺反直觉——它不来自任何互联网大厂而是由 SST 团队开发就是做 SST serverless 框架那个团队。这个背景很重要因为它决定了 opencode 的很多设计取向底层偏工程化、重插件生态、对开源集成非常友好而不是那种某个大厂为了绑定自家云服务而做的封闭工具。它的核心工作方式很简单在终端里启动一个交互式 TUI 界面你用自然语言描述需求它作为代理去读取项目代码、执行 shell 命令、读写文件、跑测试而不是像传统 AI 补全那样只在你光标后面接几行代码。这一点和 Claude Code、Codex 是同一类产品但 opencode 从一开始就把模型无关作为原则——不要求你必须用某一家的大模型。我用一个类比来解释它在工作流中的位置如果说 GitHub Copilot 是自动补全的输入法那 opencode 就是一个坐在你旁边、能自己动手翻代码、敲命令、改文件、跑测试的实习生你只需要把活儿说清楚然后 review 它干完的活。1.2 关键特性盘点多模型、Skills、Memory、MCP、LSP我用了这段时间之后觉得这几个特性是它和其他终端 Agent 拉开差距的核心多模型接入Anthropic Claude、OpenAI GPT、Google Gemini、Groq 都可以接还支持 OpenRouter 聚合和 Ollama 本地模型。这意味着你可以根据任务难度切换模型省钱和效果两头抓。Skills 技能系统通过 Markdown 格式的技能包告诉 AI 在特定场景下按什么流程干活等于给 Agent 装操作手册后面我会详细讲。Memory 持久记忆它能把项目偏好、技术栈约束、用户习惯写到本地记忆里跨会话保留。MCP 支持可以接入各种 MCP Server比如数据库、浏览器、文件系统、Playwright 等外部工具。LSP 集成利用语言服务器协议读取代码库的符号、引用、定义对大型项目的理解能力明显强于纯文本塞上下文的实现。这套组合拳打下来它的定位就不再是聊天窗口 终端而是一个可以长期参与项目维护的工程协作实体。1.3 从 TypeScript 到 Go2.0 重写背后的性能逻辑opencode go这个热搜词我猜指的就是 2.0 的 Go 重写。旧版用 TypeScript/Node 实现功能没问题但启动延迟和流式响应都有点重。2.0 用 Go 重写整个引擎之后启动时间降到几百毫秒级别内存占用也明显下降。为什么性能在这种工具里这么敏感因为 Agent 的工作模式是高频小步迭代——每次工具调用、每次文件读取、每次流式 token 输出都有固定开销。如果一个操作要等几百毫秒才出结果你连续看十次就会烦躁如果每次循环都快整个体验就完全不一样了。我自己的体感是Go 重写之后的 opencode 在长任务里的手速明显更接近真人结对编程的节奏这直接影响我愿不愿意把它用在复杂重构场景里。提示如果你之前安装过旧版 Node 版本升级到 2.0 后建议把旧的全局包卸掉避免两个二进制在 PATH 里打架。这个坑我后面踩坑章节会展开。2. 安装全流程Windows / macOS / Linux 三种方式与首次启动2.1 三种安装方式怎么选opencode 官方推荐的安装方式有这么几种我列个表直接对比安装方式命令适用场景官方脚本curl -fsSL https://opencode.ai/install | bashmacOS / Linux 最快上手npm 全局安装npm install -g opencode-ai已装 Node 生态、方便统一管理Homebrewbrew install sst/tap/opencodemacOS 用户习惯 brew 管理Go 安装go install github.com/sst/opencode/cmd/opencodelatest已经用 Go、想要最新构建手动下载GitHub Releases 下载对应平台二进制Windows 或内网环境我个人的建议是macOS 用户直接 brewLinux 用户用官方脚本Windows 用户优先用 WSL或者直接装桌面版。如果你不想折腾npm 全局安装是兼容性最好的但要注意 npm 全局 bin 目录的 PATH 问题这正是后面那个报错的来源。2.2 首次启动登录鉴权与模型选择装好之后在终端运行opencode第一次启动会进入配置引导它会检测你系统里的环境变量比如ANTHROPIC_API_KEY、OPENAI_API_KEY如果检测到就直接可用没有的话会提示你执行opencode auth login这个命令会自动打开浏览器按提示走一次授权流程。当然如果你不想走交互登录也可以直接在 shell 配置文件里导出 API Key相当于手动注入凭据。进入 TUI 之后第一件事是选择模型。我建议用/models命令打开模型列表这里面会展示当前已配置 provider 下的所有可用模型。如果列表为空说明你的 provider 还没配好回到下一章继续看。初次上手我推荐先用一个够用但不贵的模型跑通流程比如 Claude Sonnet 系列或 GPT 系列的中端型号不要一上来就用最贵的 Opus因为 Agent 场景一个任务会产生大量 token费用涨得比你想象快。2.3 Windows 下无法将 opencode 识别为 cmdlet的根因与解法热搜里那条opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名是所有 Windows 新手最容易撞上的报错。它的本质很简单Windows 在 PATH 环境变量里找不到名为 opencode 的可执行文件。如果你用的是 npm 全局安装先查一下 npm 的全局 bin 目录在哪npm prefix -g正常情况下输出类似C:\Users\你的用户名\AppData\Roaming\npm。然后检查这个路径是否在 PATH 环境变量里打开系统属性 - 环境变量在 Path 里添加这一行保存后重新打开一个终端窗口——注意是重新打开不是继续用旧窗口因为环境变量只在进程启动时读取一次。如果你用的是官方脚本或手动下载的二进制确认一下下载的文件路径把它所在目录同样加进 PATH。还有一个更省事的选择直接安装 opencode Desktop 桌面版绕开终端环境变量这堆事。注意如果之前安装过旧版先执行npm uninstall -g opencode-ai或删除旧二进制再装新版。两个版本共存会让 PATH 里出现旧版本优先的问题到时候你会排查半天。3. 模型接入与配置官方 API、OpenRouter、免费模型到底怎么配3.1 官方模型接入Anthropic 与 OpenAI 的直连先说不绕弯的。你要用 Claude就要有ANTHROPIC_API_KEY要用 GPT就要有OPENAI_API_KEY。在 shell 配置里导出就行export ANTHROPIC_API_KEYsk-ant-... export OPENAI_API_KEYsk-...Windows 上对应的是setx ANTHROPIC_API_KEY ...或者直接在系统环境变量里加。然后重启 opencode用/models就能看到对应模型。直连的优点是延迟低、稳定、官方 SDK 适配最好缺点是贵而且 key 管理要注意安全。我一般只在需要最强模型处理复杂任务时才切到 Opus 或最顶级的 GPT 型号常规编码用中端型号就够了。3.2 用 OpenRouter 聚合多家模型一个 Key 走天下OpenRouter 是我最常用的接入方式它解决了一个很实际的痛点不同任务想用不同模型但不想每个平台都去申请 key。OpenRouter 提供一个统一 API你只需要一个 key 就能访问它平台上的所有模型。在 opencode 里配置 OpenRouter步骤很简单去 OpenRouter 官网申请 API Key导出环境变量OPENROUTER_API_KEY。打开 opencode 模型列表选择 provider 为 openrouter。在模型列表里挑具体型号比如anthropic/claude-sonnet-4、openai/gpt-5等。在 TUI 里你可以随时用/models切换模型不用重启进程。这一点在 Agent 场景里太好用了——先用便宜模型做批量改动遇到复杂重构再切到强模型成本可控。3.3 免费/低成本方案Ollama 本地模型与 OpenRouter 免费档opencode 免费模型这个热搜我猜大家都想知道怎么白嫖。目前靠谱的路径有两条一条是本地模型一条是 OpenRouter 的 free 模型档。先讲本地模型。如果你机器内存够大32G 以上跑 Ollama 是零成本方案。安装 Ollama 后拉一个编码模型ollama pull qwen2.5-coder:32b ollama serve然后在 opencode 里选择 provider 为ollama就能看到本地模型列表。本地模型的好处是隐私好、无 API 费用、离线可用坏处是代码生成质量跟顶级云端模型还是有差距更适合完成结构性明确的机械任务比如补测试、写正则、批量改格式。再讲 OpenRouter 免费档。OpenRouter 上有一部分标着free的模型用它们不扣额度但稳定性一般。我实测下来免费模型经常会在长任务中途超时或限流所以我的建议是可以拿来体验和低强度任务但别拿它跑重要生产级任务。3.4 opencode.json 配置字段拆解项目级和全局级优先级opencode 的配置采用 JSON 文件全局配置在~/.config/opencode/opencode.json项目级配置在你的项目根目录opencode.json。两个文件可以同时存在项目级配置会覆盖全局配置的对应字段。一个最小可用的配置长这样{ $schema: https://opencode.ai/config.json, provider: openrouter, model: anthropic/claude-sonnet-4, agent: build, permissions: { read: true, write: true, run: [node, npm, git, go, mvn] } }字段说明$schema编辑器智能提示用推荐保留。provider默认的模型提供商。model默认模型。agent默认使用的 Agent 模式。permissions控制 Agent 能读取、写入和运行的命令白名单。这个字段非常实用限制到白名单之后能防止 AI 在执行任务时乱跑命令。关于权限配置我有一个血的教训早期我把run设成了true放开所有命令结果有一次它为了修复一个权限问题直接对我的 git 配置下了手虽然不是破坏性操作但确实折腾了我好一阵。后来我改成白名单制只在有明确需要时才临时放开某个命令安全性和可控性都好了很多。4. 实战工作流从帮我写个函数到接手整个项目4.1 基础交互斜杠命令、Agent 模式与 Plan 模式安装配置完成后的第一件事是熟悉 TUI 的基本操作。opencode 的交互主界面由对话区、输入框和状态栏组成最常用的斜杠命令有这么几个命令作用/models切换模型/agents切换 Agent 模式build / plan / custom/skills启用或查看技能/memory查看和管理持久记忆/help查看全部命令我强烈建议你养成一个习惯大改动先切到 plan 模式。plan 模式下 Agent 不会直接改代码而是先读代码、分析方案、输出计划等你确认后再执行。对于重构某个模块迁移数据库字段这种任务plan 模式能避免 AI 一头扎进去改出一堆你不想看到的中间态。确认计划没问题之后再切回 build 模式让它真正动手。4.2 skills 技能包用 superpowers 规范 Agent 行为opencode skills和opencode 安装 superpowers这两个热搜一起看就懂了——skills 是 opencode 的灵魂之一。一个 skill 本质上是一份 Markdown 指南它告诉 AI 在特定场景下应该遵循什么步骤、注意什么边界。没有 skills 的 Agent 像一个有潜力但缺乏经验的开发者有了 skills 之后它才像手边摆着团队规范文档的老手。社区里很火的一套技能包是 superpowers也就是 Jesse Vincent 开源的那套 skills 集合由一系列可组合的技能组成从如何拆分任务到如何做 TDD 调试都有。安装方式是把技能包克隆到 opencode 的技能目录git clone https://github.com/obra/superpowers.git ~/.config/opencode/skills/public/superpowers装好后在 opencode 里运行/skills就能看到并启用。我实际用过之后最大的感受是启用 superpowers 里的 debug 技能后AI 面对一个诡异的 bug 不会再猜一个改法试一下而是会按先复现 - 二分定位 - 打日志 - 验证修复的流程走明显更靠谱。4.3 memory 记忆让 Agent 记住你的项目偏好memory 是 opencode 比较有特色的功能。它可以把项目相关信息——比如这个项目用 pnpm 不用 npm接口返回统一包一层 data 字段测试文件必须放在tests目录——持久化保存之后所有会话都能读取。你可以在对话里直接让 AI记住某个规则它会自动写入 memory也可以主动编辑记忆文件。我带新项目的时候第一件事就是把项目约定写进 memory后面所有 Agent 会话都会遵守这些约定省去反复强调的沟通成本。不过 memory 也要注意污染问题。我踩过的坑是让 AI 记住了一个只针对某个临时分支的规则结果其他项目也读到了产生了一些莫名其妙的“符合规范”的改动。所以项目特殊的规则尽量放在项目级配置或项目级 memory 里别放到全局。4.4 用 opencode 接手存量项目的正确姿势opencode 接手开发项目这个场景我觉得是它最实用的地方。拿到一个从没见过的代码库过去我会花大半天读文档、理目录结构现在我会让 opencode 先帮我做一次代码库侦察。我会这样下指令这是我从没接触过的项目。请先分析项目结构、核心模块和技术栈输出一份项目概览包括主要目录职责、关键入口文件、数据流方向、构建测试命令。不要修改任何代码。由于 opencode 自带 LSP 能力它能真正读取代码符号和引用关系而不是只做关键词匹配。过几分钟我就能得到一份相当靠谱的项目结构说明比人肉翻代码快得多。然后我会让它基于这份概览去实现一个小需求通过这个小需求验证它对项目的理解是否准确——如果理解有偏差就当场纠正把正确理解写进 memory。这个流程走下来接手一个中型项目的时间和切换成本明显下降。4.5 用 Playwright 测试前端 bug从复现到回归的一条龙opencode playwright 怎么测试前端 bug这段时间问的人很多我分享一下自己的用法。opencode 通过 MCP 接入 Playwright 之后可以把浏览器操作能力交给 Agent让它像人一样打开页面、点击、输入、截图。实际的 debug 流程是我把 bug 描述给它比如登录页在移动端视口下验证码按钮被遮挡点击无效然后让它用 Playwright 打开本地开发服务器设定移动端视口复现问题并截图。它会把截图路径返回给你你一看就知道问题是不是真的存在。定位到问题后它再回到代码里修复修复完再用 Playwright 跑一遍同样的操作验证。这个工作流的价值在于闭环传统的 AI 修复全凭文本理解经常修了 A 坏了 B而有了 Playwright 的验证环节Agent 能自己确认修复是否有效。我实际用下来前端 bug 的一次修复成功率明显提升。5. 编辑器与桌面端集成VSCode、JetBrains 与 Desktop 的适用场景5.1 VSCode 插件在编辑器里直接使用 opencode如果你主要用 VSCode从扩展市场搜opencode安装官方插件即可。装完之后侧边栏会出现 opencode 面板你可以在编辑器里直接对话它会读取当前打开的代码选区作为上下文回复里的代码还支持高亮和直接插入文件。用插件的好处是不用在终端和编辑器之间来回切换。我个人的工作流是简单问题直接在 VSCode 侧边栏问复杂重构回到终端 TUI 里操作。而且两者共享同一套配置和 memory切换成本很低。有个使用细节建议在 VSCode 插件里如果 Agent 要跑前端项目最好让它调用集成终端而不是普通调试终端否则有些 dev server 的输出捕获不到。5.2 JetBrains IDEA 插件与 Maven 项目注意点JetBrains 系的插件在 IDEA 插件市场里同样能搜到。安装后会在右侧工具窗口出现 opencode 面板操作逻辑和 VSCode 版类似。Java/Maven 项目有一些额外的注意事项这也对得上opencode mvn配置这个热搜。首先是确保 PATH 里能找到mvn命令IDEA 内置的 Maven 路径和终端 PATH 不一定一致。opencode 执行 shell 命令时用的是系统环境变量所以要在系统层面把 Maven 配好而不是只在 IDEA 里配。其次如果项目用了多模块 Maven 结构建议让 opencode 优先使用mvn -pl 模块名 test这样精准的命令而不是mvn test否则它每次验证都要全量构建慢得让人着急。我一般会在项目级配置的 permissions 里把 mvn 加入白名单同时把常用的模块构建命令写进 memory。5.3 Desktop 桌面版适合什么场景opencode 桌面版也是热搜词之一。Desktop 版是独立图形界面把终端 TUI 搬到了原生应用里配置、模型切换、skills 管理都做了可视化。我的体验是Desktop 适合两类场景。一类是 Windows 用户——它能绕开 PowerShell 那些环境变量和编码问题开箱即用另一类是多项目切换频繁的使用者——Desktop 的项目管理界面比终端更直观可以同时挂多个项目的会话。不过如果你已经习惯了终端 TUI 的效率操作Desktop 并不带来额外的能力只是换个壳。我的建议是新用户从 Desktop 入门降低门槛老用户回到终端提高效率两者共用配置不冲突。6. 踩坑实录从安装到实战的高频报错与完整排查链路6.1 error: unexpected server error 的完整排查过程热搜里那句c:\windows\system32opencode error: unexpected server error. check server lo...我太熟了也踩过不止一次。这个报错的特点是信息量极少根本没有告诉你哪一层出了问题。所以排查需要按链路一步步来看日志opencode 的日志通常在~/.local/share/opencode/log目录macOS/Linux或对应用户目录的 AppData 下。先看日志找更具体的错误信息。排除配置问题检查当前选的 provider 是否真的配置了有效 API Key可以先用 curl 直接请求 API 确认 key 和网络没问题。检查网络环境如果你的环境有代理或防火墙API 请求可能超时。这个需要在系统层面处理我不展开。确认模型名是否有效有时候 OpenRouter 上的模型会下架或改名而你的配置里还留着旧模型名。opencode 会返回 unexpected server error实际是模型不存在。解决办法是用/models重新选择有效模型。重启进程如果以上都排除了直接退出重开。opencode 2.0 的守护进程偶尔会进入异常状态重启能解决大部分莫名奇妙的报错。排查的顺序之所以重要是因为很多人一看到报错就重装浪费时间。先日志、再配置、再网络这个顺序能覆盖绝大多数情况。6.2 ccswitch 配置后不生效优先级问题ccswitch配置opencode这个热搜指向的是不少人在用的模型/provider 切换工具。它可以集中管理多个服务商的配置一键切换。但有个高频问题在 ccswitch 里切了之后opencode 里没变化。根因多半是配置读取优先级。opencode 会按项目级配置 全局配置 环境变量 外部工具写入的配置的顺序读取ccswitch 如果写的是它自己的全局变量但 opencode 项目级配置文件里显式指定了另一个 provider那自然是项目配置赢。排查链路先看项目根目录有没有opencode.json有的话先确认它的 provider 和模型字段再看全局配置~/.config/opencode/opencode.json最后确认环境变量有没有导出冲突的 key。改完之后一定记得退出 opencode 进程再重开配置只在启动时读取。6.3 免费的 hy3-free 模型下线第三方免费端点的脆弱性opencode hy3-free 下线了吗这个问题答案是确实说过就过。社区里出现过一些第三方免费模型端点打着免费高速的旗号被用来接入各种 Agent。这些端点最大的问题就是不稳定——要么突然限速要么直接关停而且你无法确认请求的数据被谁看到了。我的态度很明确免费端点可以尝鲜不要依赖。真正的生产力场景要么用官方 API 走量控制成本要么用本地 Ollama 零成本跑私有任务。把核心项目依赖在一个随时可能消失的第三方免费服务上是给自己埋雷。6.4 oh-my-claudecode 与 opencode 混用时的 PowerShell 冲突oh-my-claudecode 是一套给 Windows PowerShell 用的脚本集很多人装它是为了在 PowerShell 里舒服地使用 Claude Code 等工具其中会注册一堆 alias 和函数。问题就出在这里这些自定义函数里如果有覆盖opencode的包装逻辑PowerShell 在解析命令时函数优先级高于 PATH 中的可执行文件于是你运行的opencode其实是脚本里的旧包装函数行为就会很诡异。排查方法很简单执行Get-Command opencode -All如果输出里列出了函数Function 类型就说明被覆盖了。解决办法是直接调用完整路径绕过 alias或者把 oh-my-claudecode 的包装函数改名避免冲突。6.5 配置文件的坑字段冲突与覆盖关系最后一类坑集中在配置本身。permissions.run如果设置了命令白名单你又想让 Agent 执行某个不在白名单里的命令它会失败。这时候不要直接改配置成true更稳妥的做法是把那个命令加进白名单数组。再有一个常见的坑是项目级配置里的 model 字段你明明在/models里切到了 A 模型但重新打开后它又回到配置里的 B 模型。这是因为/models的切换是临时的不写回配置文件。想让默认模型固定下来就去项目级配置改model字段。7. 横向对比与选型建议opencode、Codex、Claude Code、Pi 怎么选7.1 四款工具的核心定位差异最近opencode codex claude code哪个 agent 好用这类对比特别多社区里还有把 Codex、Claude Code、Pi 和 opencode 放在一起比的。它们表面都是终端 Agent但骨子里的定位差异很大。Claude Code模型能力最强的官方终端 Agent深度绑定 Claude 系列交互设计打磨得非常好适合就想用最强模型 不差钱的用户。CodexOpenAI 的终端 Agent和 GPT 系列模型绑定和 GitHub 生态结合好但相对封闭扩展性弱一些。Pi这个是近期讨论度逐步上来的新竞争者同样主打终端交互但生态成熟度还在早期我在实际项目里没有大规模使用暂时作为观察对象。opencode最大的差异点是模型无关 完全开源 扩展生态丰富。它把模型层抽象得很好Anthropic、OpenAI、本地模型、聚合平台都能接而且 skills/memory/MCP 的开放程度是目前这几个里最高的。7.2 实测对比表我根据自己连续几周的实际使用做了一张主观但诚实的对比表对比维度opencodeClaude CodeCodexPi模型自由度高支持多家本地低绑定 Claude低绑定 OpenAI中等开源程度完全开源MIT闭源闭源部分开源启动性能Go 重写后快中等中等中等Skills/Memory 生态丰富、开放有 Skills 但封闭较弱早期IDE 集成VSCode JetBrains 桌面版插件依赖官方VSCode 插件较少上手门槛中等配置项多低低低长任务稳定性高实际体验高中等中等7.3 我的选择和理由如果你是完全的新手急着上手我会推荐 Claude Code它的官方开箱体验最平滑但如果你和我一样希望用一个工具对接多个模型、本地跑私有任务、并且能深度定制 Agent 行为opencode 是更值得投入的那个。我的最终选择是 opencode 作为主工作流保留 Claude Code 作为特定场景备选。原因很简单我把团队项目的短期需求都写在项目级配置和 memory 里无论底层模型是 Anthropic 还是 OpenAI 还是本地模型opencode 的交互层和技能层是稳定的。这种底层模型可以换工作流不塌的特性才是它最打动我的地方。最后再分享一个实际经验不管用哪个 Agent把它当成一个能力很强但没有项目经验的协作者而不是一个全知全能的神。在关键操作前让它先说计划在它动手后认真 review diff把这套流程固化成习惯你才能真正享受 AI 编程代理带来的效率提升而不是被它制造的新问题折腾得焦头烂额。