从Claude Code迁移到opencode：终端AI编程助手安装配置与实战全记录

最近把终端里的AI编程工具从Claude Code换成了opencode，折腾了小一周，终于把安装、配置、模型接入、编辑器插件，再到真实接手一个项目跑完整流程，全部摸了一遍。opencode是一个开源的AI编程助手（coding agent），简单说就是在终端里跑一个"能读懂你项目"的AI对话工具，它不只是聊天，而是能读取项目结构、理解代码逻辑、改bug、跑测试、调命令，甚至可以配合Playwright做前端问题排查。它最大的特点是不绑死某一家模型，而是做成了一套开放框架，支持OpenAI、Anthropic、Google、本地Ollama等多种模型源自由切换。

这篇文章不是官方文档的翻译，是我自己从零开始用的完整记录，包括安装时踩的坑、配置文件怎么写、怎么配合CC Switch管理多套模型Key、Skills机制怎么用，以及在真实项目里如何让它从需求描述一路干到跑通测试。适合刚听说opencode、准备从Claude Code或者Codex CLI迁过来的朋友，也适合那些已经装好但不知道怎么配多模型、写skills的人。

1. opencode到底是什么来头？为什么大家都在换

1.1 背靠Charmbracelet的开源项目

很多人在热搜里问"opencode是哪家公司的"，答案是Charmbracelet。老终端玩家对这个名字应该很熟，他们做了一堆提升终端体验的开源项目，比如Glow、Gum，风格统一、交互细腻，把命令行工具做出了精致感。opencode就是他们出的AI编程助手，代码开源，可以在GitHub上直接看到源码和issue讨论。

opencode的架构和很多同类工具不一样：它不是单个进程硬跑，而是拆了一套本地server加终端客户端的结构。你敲一个opencode命令启动的是客户端，它背后还会拉起一个本地服务，负责和模型API通信、维护会话状态、调度工具调用。这种设计的直接好处是，多个终端窗口、编辑器插件、桌面版共享同一个后端，不会各说各话。

另外它还有一个很核心的设计：模型供应商（provider）是可插拔的。默认配置就能接主流大模型，同时也可以指到本地Ollama，这让它在"中立性"上比Claude Code和Codex CLI都要激进。Claude Code天生是Anthropic生态的，Codex CLI则更贴近OpenAI那套，而opencode的目标是让"模型"变成一种可随时替换的组件，而不是被某个厂商绑定。

1.2 opencode、Claude Code、Codex CLI怎么选

这三者放一起比较是每个想换工具的人都会做的事。我自己是三个都用过一段时间，主观感受差异挺大。

选型逻辑要看你最在意什么。如果公司里已经统一买了某家API，那直接用对应的官方便签工具最省心；但如果像我这样，手头同时有OpenAI的key、Anthropic的key，有时还想用本地模型跑小任务，那opencode的"一框架管所有"优势就非常明显。它的TUI终端交互也做得相当顺手，支持主题、多会话、命令补全，长期盯着终端干活的人会很喜欢。

还有一点值得提，opencode的client和server分离让远程开发变得很舒服。我经常在本地起一个opencode服务，然后从另一台机器的终端连过去，或者通过SSH在服务器上跑一套，本地用同一个客户端操作，体验很顺滑。这个架构在上手初期感知不强，但用到后面会发现这就是它比一堆"单进程工具"更耐折腾的根本原因。

2. opencode安装与启动：从零到能跑

2.1 三种安装方式，挑一个适合你的

安装opencode的方式比较灵活，主流有三种，我分别试过，说下各自的使用场景。

第一种是官方脚本安装，适合Mac和Linux用户。终端里直接执行安装脚本，装完会提示你把它加到PATH里，然后重开一个终端窗口就能用。这种方式的优点是快、省心，官方发布的版本直接装上，升级也方便。

第二种是用Homebrew这类包管理器。在macOS上，如果你已经习惯用brew管理软件，直接搜一下opencode对应的formula，装上之后和其他软件一样统一管理，升级也是brew upgrade一步到位。对已经重度依赖brew的开发者来说这是最舒服的路径。

第三种是用npm全局安装。opencode有对应的npm包，Node.js环境里执行npm i -g opencode-ai就行。Windows用户如果不太想碰WSL，这种方式通常是最不容易出问题的，因为npm的全局bin目录只要配置正确，命令马上就能识别。装完之后一定记得先跑一下opencode --version，确认命令真的生效了再往下走，别等配置完才发现装了个寂寞。

提示：不管用哪种方式，安装完第一次运行之前，最好确认终端的PATH已经包含对应的bin目录。macOS的Homebrew脚本在Apple Silicon上容易把路径指到/opt/homebrew/bin，如果没在PATH里，就会出现"命令找不到"的问题。

2.2 Windows下"无法将opencode项识别为cmdlet"怎么解决

Windows用户最常遇到的就是这个错误，热搜里那个"无法将opencode项识别为cmdlet、函数、脚本文件或可运行程序的名"基本是每个用PowerShell装完新命令行工具都会撞见的。原因一般就两个：一是安装目录不在PATH环境变量里，二是你装完之后当前PowerShell会话还是老环境变量，没重新加载。

解决方法分三步走。第一步，关掉当前终端窗口，重新开一个，先看看echo $env:Path里包不包含安装目录。第二步，如果确实没有，把opencode安装目录手动加到系统PATH，Windows的设置里搜"环境变量"，编辑Path，新增这一条，然后重启终端。第三步，如果你是拿npm全局安装的，确认npm的全局根目录（npm config get prefix得到的路径下的bin或cmd目录）已经加进PATH。

注意：Windows上我更推荐用Windows Terminal配PowerShell来跑这类工具，默认UTF-8编码，中文输出和文件路径都不容易出问题。如果还是用老版cmd，经常会遇到中文乱码、路径带空格导致命令解析失败的花式坑。

另外很多人在C:\Windows\System32>这种目录下直接敲opencode报错，这也是PATH问题，但还有一层原因是System32根本不需要放任何全局工具，你只是恰好在这个目录下执行命令而已。如果npm全局路径加好了，在哪个目录下敲都一样。

2.3 首次启动：从聊天界面到本地server

装好之后，直接敲opencode就会进入TUI交互界面。第一次启动时它会引导你配置模型供应商，这时候需要准备至少一个API key。如果你的key是从环境变量读的，它会自动识别；如果没配，它会给你一个交互式配置入口。

opencode的命令分成两种使用方式。一种是直接opencode进交互式聊天；另一种是opencode serve把后端server跑起来，之后可以通过其他终端、编辑器插件或桌面版连接它。这种模式对团队协作特别有用——后端在服务器上跑着，前端在各自电脑上连，不需要把代码仓库拉来拉去。

实际用的时候我还发现，它会把配置和会话数据放在用户目录下的.config/opencode这类位置，包括鉴权信息、模型配置、历史会话。换机器的时候，把这些配置同步过去，就能无缝接着上次的会话继续聊。这个体验说实话比很多大厂工具做得都要好。

3. 模型接入与配置：从云端大模型到本地小模型

3.1 配置文件怎么写，Provider怎么理解

opencode的核心配置就是定义"provider"。每个provider代表一个模型服务来源，可能是OpenAI、Anthropic、Google，也可能是本地Ollama，甚至是你自己搭的兼容OpenAI协议的服务。配置文件里会声明API的地址、key、默认模型名、参数等。

以我常用的配置为例，大概是下面这样：

model: gpt-4o provider: openai: api_key_env: OPENAI_API_KEY base_url: https://api.openai.com/v1 anthropic: api_key_env: ANTHROPIC_API_KEY ollama: base_url: http://localhost:11434/v1 models: - qwen2.5-coder:14b

这里有个概念需要理解：很多本地工具和模型网关都兼容OpenAI的接口格式，所以opencode可以通过一个统一的OpenAI兼容协议去对接各种来源，只要把base_url指过去、key填对、模型名写对就行。这也是它能做到"多模型自由切换"的技术基础。

配置好之后，在聊天界面里可以用/model之类的命令随时切换模型，比如从gpt-4o切到claude-sonnet，再切回本地模型。切换时它会保留当前对话的上下文，不会因为换模型就失忆。

3.2 配合CC Switch实现多Key切换

热搜词里"ccswitch配置opencode"出现了很多次，说明不少人都在用CC Switch这个工具。CC Switch是一个管理多个API key和模型配置的开源小工具，解决的痛点很简单：当你同时有多个模型供应商的key，或者同一个供应商有多套key（比如公司账号和个人账号），频繁改配置很痛苦。CC Switch可以统一管理这些凭据，通过一个本地接口让你快速切换。

opencode接CC Switch的方式，本质上还是在配置里把base_url指到CC Switch提供的本地地址，并读取它当前激活的那套凭据。好处是，你在CC Switch里切一下，opencode后续请求用的就是新key了，不用重启、不用改文件。我自己一般会把不同项目的预算分开管理，做高成本实验时切到有额度的key，日常小任务则用成本更低的模型，切换成本几乎为零。

提示：CC Switch这类工具只是个凭据管理器和配置切换器，它本身不会改变你访问模型服务的合规边界。无论怎么切换，都要确保用的key和模型服务是自己合法申请、符合服务商条款的。团队里如果要共享key，建议统一走公司的密钥管理系统，而不是在群里传来传去。

3.3 本地模型：把Ollama接进来

本地模型是opencode的另一大卖点。我主要用Ollama跑开源模型，比如qwen2.5-coder，它是个不错的代码模型，在14B这个量级上表现已经能用。

流程很简单：先装Ollama并启动服务，ollama pull qwen2.5-coder:14b把模型拉到本地。然后像上面配置里那样，在opencode中加一个Ollama provider，base_url指向http://localhost:11434/v1，模型名填你在Ollama里拉下来的那个，保存配置就能用了。

实测下来，本地模型适合的任务类型很清晰：代码解释、简单重构、生成单元测试、批量改样式这类对"常识"要求不高的活，本地模型完全能扛。但涉及多文件架构调整、框架迁移、复杂bug定位这种需要大语境理解的任务，14B模型的短板就体现出来了——上下文一长，容易丢前面的信息，给出的修改方案经常是"看起来对但一跑就挂"。所以我的策略是"重活用云端，轻活用本地"，又省钱又稳。

3.4 关于"免费模型"和第三方渠道的态度

热搜里还有"opencode免费模型""hy3-free下线了吗"这类问题。说实话，依赖某个第三方免费模型渠道本身就是有风险的事——下线、限流、key泄露，哪天出问题你都控制不了。我之前也图省事试过一些社区渠道，结果用到一半不是超时就是报错，反而耽误时间。

我的建议很直接：如果只是尝鲜，用各家官方提供的试用额度，或者跑本地开源模型；如果是日常工作流，老老实实买正规的API。不要把整个开发流程赌在一个随时可能消失的免费渠道上。稳定的工具带来的效率提升，远大于省下来那点token钱。

4. 实战：用opencode接手一个项目的完整流程

4.1 让Agent理解项目结构，先别急着改代码

opencode不是那种上来就帮你写代码的工具，它更擅长"理解任务后执行"。想让它在项目里干活，第一步不是让它改东西，而是让它把项目吃透。

我的习惯是启动会话后，先让它做三件事：列出项目目录结构、读README和核心模块入口文件、描述一下这个项目的技术栈和架构。opencode会自动追踪项目里的关键文件，并在对话里给出它看到的上下文，你可以根据它的回答判断它到底有没有理解对。这个环节很重要，因为一旦它理解错了，后面所有修改都会越跑越偏。

这里还涉及一个实践技巧：在项目根目录放一份AGENTS.md或CLAUDE.md之类的说明文件，把项目的编码规范、目录约定、常用命令、坑点写进去。opencode在每次对话时会自动读取这类文件作为上下文，相当于你给AI写了一份"入职说明"。我们团队现在的新项目都会顺手维护这份文档，效果比每次在对话里重复解释好太多。

4.2 从一个bug到修改完成，完整跑一遍

说一个我实际处理的场景。有一个Java的报表导出项目，用户反馈导出的CSV时间字段少了一天。我在opencode里直接说："报表导出模块的CSV时间字段比用户本地时间少一天，帮我定位原因并修复。"

opencode的处理过程是：找到导出模块相关代码，发现时间格式化用的是UTC时区；接着定位到日期格式化的工具类；然后自动搜索项目里有没有统一的时区配置；最后给出了一个修改建议——把时间格式化的时区改成项目配置里声明的业务时区，并顺手在测试里补了一条用例。

这个过程中我并不只是看结果，而是会让它解释每一步修改的理由。它给出的每个改动，我都会问一句"为什么这么改""会不会影响其他地方"。在它应用修改前，我会先确认文件是不是在git版本控制里，确保改坏了能回滚。最后让它跑一下相关的单元测试，确认没有破坏别的功能。

整个流程下来，我的角色更像是一个"代码评审人"，而不是一个操作者。AI负责高速完成搜索、理解、修改，我负责把关方向和质量。这种协作方式下，一个原本可能花费两小时的bug修复，压缩到了二十分钟左右，而且代码质量我自己亲眼审查过，敢提交。

4.3 用Playwright测前端bug，这是真香现场

热搜里有"opencode playwright 怎么测试前端bug"，这个我确实专门试过。背景是同事反馈一个后台管理页面的筛选按钮点了没反应，但控制台没报错，肉眼也看不出问题，需要自动化手段来复现。

我的做法是：本地先起好前端开发服务，然后在opencode里描述问题，并让它用Playwright写一个自动化脚本来复现。给它的输入大概包含页面URL、操作路径（点击筛选按钮、选择日期范围、点击查询），以及期望看到的结果。opencode会自己创建一个Node脚本，启动无头浏览器，模拟点击，捕获网络请求和控制台输出，然后根据结果自动调整脚本。

下面是它生成的一个简化版脚本，去掉了一些项目自身的细节：

const { chromium } = require('playwright'); (async () => { const browser = await chromium.launch(); const page = await browser.newPage(); page.on('console', msg => console.log('[console]', msg.type(), msg.text())); page.on('requestfailed', req => console.log('[failed]', req.url(), req.failure()?.errorText)); await page.goto('http://localhost:3000/list'); await page.click('button[data-testid="filter-btn"]'); await page.fill('input[data-testid="start-date"]', '2025-01-01'); await page.fill('input[data-testid="end-date"]', '2025-01-31'); await page.click('button[data-testid="submit"]'); await page.waitForTimeout(2000); await page.screenshot({ path: 'debug.png', fullPage: true }); await browser.close(); })();

脚本跑出来之后，发现点击筛选后请求根本没发出去，原来是一个第三方日期组件初始化失败，把整个事件链吞掉了。opencode通过读取运行日志和页面快照定位到了这一步，帮我把排查范围缩到了具体组件。这个活儿如果纯手工查，少说一小时，用AGENT陪跑，不到二十分钟就解决了。

关键心得是：opencode不是"帮你写测试"的工具，它是"协助你快速复现问题"的脚手架。你要做的是给它足够清晰的操作步骤和期望行为，它会负责把脚本写对、跑起来、把失败信息读回来。你不必精通Playwright，但至少要懂一点浏览器调试的基础，不然它给出错误的结论时你也判断不了。

5. Skills、Memory与团队协作：让Agent越用越顺

5.1 Skills机制：给Agent装"技能包"

Skills是opencode里一个很值得玩的功能。你可以把它理解为预置好的"技能包"——一段固定的指令、规则或者工作流模板，需要时通过@技能名这种方式在对话里唤起。比如你可以写一个"代码评审"skill，里面规定它必须检查哪些方面、以什么格式输出结论、发现严重问题时要怎么标记；也可以写一个"提交信息规范"skill，让它帮你生成符合团队格式的commit message。

实际使用中，我把常用的skill放在项目的.opencode/skills目录下，每个skill就是一个Markdown文件，里面用结构化写法描述触发条件、执行步骤、输出格式。opencode看到用户用@某个skill唤起时，就会读取这个文件并按照里面的规则执行。

热搜里提到的"opencode安装superpowers"，本质就是从社区或某个插件集中导入一组现成的预置技能。这类技能集确实能让你少写很多重复规则，但我的建议是装之前一定先看一遍它们的实际内容，弄明白每个skill会对Agent的行为产生什么影响。曾经有人装过来路不明的skill包，里面被塞了带风险的指令，所有AI操作都会先去请求某个外部接口，这种后门式的东西想想就后怕。

注意：开源生态带来了便利，也带来了供应链攻击的风险。无论装插件、装skill还是用别人写的Agent脚本，先审查再执行，尤其是那些需要联网、需要读取密钥、需要执行shell命令的内容。

5.2 Memory：跨会话保存项目上下文

另一个热搜词是"opencode memory"。用过这类工具的人都知道，最讨厌的事情是每次开会话都要重新解释一遍项目背景。opencode的Memory机制就是为了解决这个问题的。

我的用法并不高端但很有效：在项目根目录维护一份MEMORY.md，每次会话结束，让opencode把本次修改的内容、遗留问题、下一步计划总结到这份文件里。第二天新开会话，直接说"读取MEMORY.md，按里面的计划继续"，它就能接上昨天的上下文，不需要我重新粘贴大段背景。

这种方式比它内置的对话历史记忆更可控。对话历史可能会越来越长，影响模型上下文窗口；而MEMORY.md是一份经过总结的、人类可读的"状态存档"，既方便AI读取，也方便人类同事review。我们团队现在几乎每个长期项目都有一份这样的文件，它相当于项目的"活文档"。

5.3 团队协作配置：把规则沉淀到仓库里

当opencode在一个团队里使用时，最值得做的事就是统一配置和规则。我们把AGENTS.md、MEMORY.md、公共skills目录都提交到代码仓库，这样每个成员clone下来就有整套Agent工作流，不用各自重复配置。

API key这类敏感信息则是严格不进仓库的，每个人用自己本地的key，通过环境变量或者CC Switch管理。团队内部会约定默认模型和成本上限，比如日常小任务用成本低的模型，重大架构讨论才切到旗舰模型。opencode的配置支持按项目覆盖，所以我们会在不同仓库里设置不同的默认模型，尽量做到"开箱即用、各取所需"。

这里还想提醒一句：团队里使用AI编程助手，重点不是比拼谁的Agent更花活，而是把"人怎么审查AI产出"的流程定下来。没有代码评审的AI提交，就是在给代码库埋地雷。我们把"AI提交必须关联issue、必须过CR"写进团队约定，用了一个季度下来，代码质量基本没翻过车。

6. 编辑器集成：VS Code、JetBrains插件与桌面版

6.1 VS Code插件：选代码直接发给Agent

VS Code插件大概是opencode编辑器集成里最成熟的。在扩展市场搜"opencode"就能找到官方插件，装完之后，它会在侧边栏生成一个面板，功能上和终端TUI是同源的，但多了与编辑器交互的便利性。

我最常用的操作是：在编辑器里选中一段代码，右键菜单里选择"发送给opencode"，然后直接在面板里追问"这个函数哪里会有并发问题""这段代码能不能优化"。这个流程免去了切终端、粘贴代码、解释上下文的麻烦，尤其适合带着具体代码片段的问题。插件还会自动把当前打开的文件路径、选中区域带过去，Agent理解上下文更准确。

和终端TUI对比，我的体感是：日常小问题用插件面板够了，省事；但涉及多文件的重构、需要跑命令、需要观察测试结果的场景，我还是更愿意切到终端TUI，因为信息密度更高、支持的命令更全。两个客户端共享同一套后端会话，切来切去也不会丢上下文。

6.2 JetBrains IDEA插件：Java项目的正确姿势

JetBrains系IDE（包括IDEA）也有对应的opencode插件，安装方式是在插件市场搜"opencode"然后安装重启。它提供的功能和VS Code插件类似，可以在IDE里直接对话、选中代码发送给Agent、查看修改建议。

Java项目里最需要注意的地方其实是"环境一致性"。opencode在帮助执行Maven命令时，比如mvn -DskipTests package，它跑在IDE集成的终端里，环境变量会和你的IDEA设置保持一致，通常会带上JDK和Maven的配置。但如果用内嵌终端之外的方式调用，可能就找不到JAVA_HOME，需要你在项目的Agent配置里显式声明。

我的经验是，让opencode跑Maven构建之前，先确认好当前项目用的JDK版本、Maven镜像、本地仓库路径。热搜里那个"opencode mvn配置"多半就是在问这个——不是opencode需要特殊配置，而是你的Java构建环境本身得先干净，Agent干活才能顺利。IDE插件遇到按钮不响应或者构建命令报错，先看插件和IDE版本是否匹配，再查输出面板里的真实错误，往往不是opencode的问题，是环境问题。

6.3 桌面版opencode desktop：给不喜欢终端的队友用的

opencode也提供了桌面版客户端，相当于把TUI包了一层图形界面，安装包在官方Release页面可以找到，支持主流桌面系统。界面逻辑和终端里一致，左侧是会话列表，右侧是聊天操作区，能看到Agent执行命令的过程和文件变更。

我个人觉得桌面版最大的价值不是说比终端更好用，而是降低了团队里非重度终端用户的上手门槛。我同事里有几个平时用IDE为主、很少开终端的人，他们用桌面版看Agent干活的过程比用TUI舒服得多，错误信息也能直接复制。对开发者本人来说，终端TUI的效率还是要高于GUI的——GUI的渲染开销和点击成本摆在那里，但给团队做演示、给非技术人员展示进度时，桌面版确实是个更好的载体。

7. 常见问题与避坑技巧速查

7.1 高频报错与解决方案

这个表是我踩坑总结里最值钱的部分。很多问题不是opencode本身的bug，而是环境、路径、配置不一致导致的。排查顺序建议是：先复现、看日志、确认配置、再怀疑工具本身。

7.2 我的几条避坑心得

第一，不要把API key写进项目仓库里。这个错我见过太多人犯，key一旦被提交到公开仓库，分分钟就会被抓走刷额度。用环境变量、或者本地密钥管理工具，都是更稳妥的选择。

第二，给Agent执行权限要谨慎。opencode能执行shell命令、修改文件，能力很强，但也意味着危险。我的习惯是，它会先给我看要执行的命令，我确认后才放行。涉及删除、权限修改、批量替换这类操作，一定要额外谨慎，最好提前把改动提交到git，给自己留后退的余地。

第三，超大型仓库要拆任务。Agent的上下文窗口是有限的，把一个几十万行代码的仓库整个丢给它，它只会"记了后面忘了前面"。我的做法是先用规划性对话让它理解架构，再按模块分任务处理，这样每一步的上下文都不会爆炸，产出也更可预测。

第四，成本控制要提前做。跑AI编程工具最大的隐性成本就是token，尤其是多轮对话和长上下文场景。我一般会在配置里限制单次对话的模型规模和参数，避免随手就是一场几十美金的对话，月底看到账单才后悔。

第五，第三方渠道的"免费午餐"真的会害人。前文说过，免费模型渠道不是不能用，而是不稳定、有风险，它往往还涉及你无法控制的中间环节。对自己负责的方式永远是：用官方渠道的正式额度，或者跑本地模型。开发工具是拿来产出的，不是拿来赌的。

我个人在用了将近三周opencode之后的体会是，它本质上不是一个"帮你写代码的机器"，而是一个响应极快、从不抱怨的结对程序员。真正的核心价值不在于它能自动改多少BUG，而在于它能帮你把重复的搜索、定位、理解工作快速做完，让你把精力放在判断和决策上。你给它一个清晰的需求边界，它给你一个可执行、可审查、可回滚的修改方案，这种协作节奏一旦习惯，真的回不到以前纯手工翻代码的日子。

最后再分享一个小技巧：让它在每次会话快结束时，把"已完成、进行中、待处理"整理到MEMORY.md。第二天新开会话，只说一句"按MEMORY.md继续"，比你把上一段对话全部粘贴过去要好用太多。这个习惯成本极低，但长期下来，项目的连续性、Agent的理解度，都会被拉高一个档次。