我最早用AI写代码的时候基本流程是把报错信息复制到网页聊天框把AI给的补丁代码复制回编辑器然后跑一遍测试再复制新的报错。来回几轮光复制粘贴就够我喝一壶的。后来我换到终端里用opencode这个流程彻底变了。opencode是一个开源的命令行AI编程助手它会直接跑在你的项目目录里能自己读文件、改代码、执行命令还会把每个动作先展示给你确认。这篇文章是我自己用下来的真实记录包含安装、配置、日常操作、工作流和踩坑排查给想从网页聊天式工具切到终端Agent模式的开发者做参考。1. 先搞清楚opencode是干嘛的1.1 一个住在终端里的AI拍档opencode本质是一个交互式命令行程序。你启动它后不用再打开浏览器或独立的聊天窗口而是直接在你的项目根目录下进入一个全终端界面。它能看到你当前项目里的文件结构可以读取指定文件内容也可以调用你配置好的大模型接口来理解问题。关键在于它不只是“回答问题”而是会尝试动手解决问题。比如你对它说“这个接口调用顺序有问题帮我检查一下”它会先列出它准备检查哪些文件然后用工具去读文件、搜索关键字最后给出修改建议并直接写入文件。所有动作都发生在你本地的终端里不需要把代码复制来复制去。同时它保留了类似聊天工具的多轮对话能力。你可以接着上一次的对话继续问也可以在一个会话里同时处理多个子问题。因为是跑在本地终端所以会话记录保存在本地文件里不经过第三方聊天窗口存储对代码敏感性有一定保障。这也是我最初愿意尝试它的原因。1.2 与网页聊天工具的差别网页聊天式工具比较擅长大段问答但一遇到“请帮我改这个项目的某个文件”就会很痛苦因为AI没有项目上下文也不知道报错具体发生在哪一行。opencode把上下文这个问题解决了它运行在项目目录里能直接读取依赖描述文件、配置文件、源文件等还能执行搜索和命令所以对项目的理解要深入得多。另一个差别是操作粒度。网页工具给代码时往往给你整段替换容易覆盖你本地未提交的改动。opencode在修改文件之前往往会在界面里列出具体的diff片段并且要求你确认。你可能觉得“多一步确认很麻烦”但实际上这一步能省掉不少误改。尤其是当你同时在编辑器里开着同一个文件的时候AI改完你再手动保存冲突在所难免多一点交互确认反而安全。1.3 适合哪些人用如果你是个人开发者每天要在多个项目间切换经常处理重构、修bug、写测试这类任务opencode非常适合。如果你是一个小团队想在不改变现有Git工作流的前提下给开发加一个“AI结对人员”也可以让成员各自在终端里使用。它不要求你把代码推送到任何第三方平台“自己拿着项目本地跑”这个特性让它对私有代码更友好。当然如果你们团队有统一的代码托管平台它也能帮你自动生成提交信息、创建变更请求这部分后面会详细说。不适合的人群也有如果你只想要一个聊天机器人解答概念性问题并不需要它读写你的文件那网页聊天工具就够用如果你不喜欢任何形式的自动修改文件只希望别人给你建议然后你手动改opencode可能会让你觉得过于主动。但这完全可以配置限制后面也会提到。2. 安装和首次配置过程2.1 安装方式怎么选opencode的安装方式非常简单不同桌面操作系统上都有安装脚本也可以在装好Node运行时的情况下通过包管理器一行命令装完。我自己更推荐用包管理器因为更新频率高用包管理器升级会方便一些不用每次去手动执行脚本。安装完成后你在终端里输入opencode如果能看到一个TUI界面出来说明程序已经正常工作。首次启动它可能会提示你进入设置流程也可能直接进入一个空白会话但这取决于你下载的版本不同版本对首次体验的引导方式略有差异。如果你对界面布局不熟悉可以先按/?这类键查看帮助看到有/help命令也可以直接输入。提示如果你所在网络的终端下载速度偏慢可以考虑换成镜像源或者直接使用包管理器来安装。这里不展开讲网络配置。2.2 把模型接口接上opencode本身不内置大模型它需要你提供一个可调用的模型接口。它支持的主流接入方式大致有两类一类是直接使用某个云模型服务商提供的API你需要在配置里写上接口地址、模型名和密钥另一类是连接本机自建的模型服务这样请求不离开你的电脑。配置过程通常可以通过命令行向导完成运行opencode的认证或配置相关命令按提示选择供应商、粘贴API Key最后选定默认模型。也可以手动写配置文件。我比较推荐把API Key放到环境变量里而不是直接写死在配置文件中因为你会经常把配置文件分享给同事或者放到自己的配置仓库备份不小心把Key提交出去之后成本问题会让你很难过。配置的大概样子如下{ provider: { model: your-model-name, api_key_env: YOUR_API_KEY, base_url: https://api.example.com/v1 } }注意api_key_env对应的是环境变量名不是密钥本身。base_url要填能与主流接口格式兼容的地址。很多模型服务商都有兼容接口可以直接填。如果你是接本地模型base_url就填本地服务地址密钥随便填一个占位符即可。如果你用的模型服务提供商不在默认列表里opencode也允许你通过自定义provider的方式注册。这就需要你去查一下该服务商的API文档重点看base_url、鉴权方式、模型名称三个信息。2.3 配置文件里值得提前改的几个字段首次配置好后opencode会在你的项目目录或用户目录下生成一个配置文件不同版本存放位置可能叫opencode.json。有几个字段我觉得值得提前关注。第一个是默认模型。如果你日常使用某个模型比较多把默认模型设为它以后每次启动就不用反复指定。第二个是命令执行权限。opencode默认在执行命令前会征求你的同意对于部分危险命令可能还会额外拦截。你可以通过配置控制哪些命令允许自动执行哪些必须询问。建议刚开始使用的时候保持询问模式等你对它的行为模式有把握了再逐步放开个别高频命令。第三个是Instructions或系统提示文件。你可以在配置中指向一个说明文件告诉它你所在项目的技术栈、代码风格、提交信息格式等。这样它每次处理任务时都会先看到这些约束比在对话中反复强调要稳定得多。第四个是会话的保存目录。默认保存在本地某个目录下如果你在服务器上跑可能希望改到持久化磁盘避免容器重建后丢失对话历史。3. 日常操作怎么和opencode高效对话3.1 启动会话、切换项目、管理多窗口opencode的使用流程通常是在项目根目录先启动终端然后运行opencode。它默认会用当前目录作为工作区。如果你有多个项目需要处理不要在一个目录里强行让它看另一个目录的代码直接另开一个终端分别进入各自项目目录启动即可。opencode支持在同一个TUI界面里开多个会话窗口你可以用快捷键切换或并排查看。这样做的好处是一个会话专心处理前端的问题另一个会话处理后端的问题不会因为对话过长把上下文搞乱。我在实际用的时候习惯把“功能开发”“测试修复”“代码审查”分成三个会话并行推进效率比按顺序串行高不少。需要注意的是每个会话都会消耗独立的模型调用额度如果API是按token计费同时开太多对话会加速消耗建议控制数量。3.2 用和#控制上下文别让它乱翻代码opencode读取代码不会一次性把整个项目塞进上下文而是按需读取。它需要知道“应该看哪些文件”。在对话里你可以用加文件路径来明确指定某个文件或目录例如src/parser.ts。它会把该文件内容作为参考。我建议在提需求时第一次就给出最核心的几个文件路径比如报错文件、配置文件、最近改过的文件这样它能少走很多弯路。除了文件引用它还会理解#符号引用比如你在某个符号、函数名前面加上#它就知道你指的是代码里的那个定义。这个功能在讨论“某个函数为什么这样实现”时很好用。不要指望它自己从零开始全项目搜索虽然它也能做但搜索也会消耗时间和token给明确的文件路径永远是效率最高的。3.3 常用斜杠命令与快捷键在对话输入框里斜杠命令是opencode提供的一个快捷入口。不同版本命令稍有差异但有几个是通用的/new新建一个会话/help查看所有可用命令/undo撤销它刚做的文件修改/compact压缩当前会话上下文。/compact特别值得说一下对话长了之后上下文接近上限模型表现会下降这时候执行一下压缩能清理掉对话早期阶段的低频信息把核心要求保留下来效果很明显。快捷键方面我常用的是CtrlN新建会话、CtrlL清空当前会话的显示内容、CtrlC取消当前正在生成的操作。如果你在一个多窗口界面里还可以用快捷键在窗口之间跳转。这些快捷方式在不同终端模拟器里可能会有冲突如果你的键没反应优先检查是不是终端占用了这几个组合键。注意清空显示内容和清空上下文不是一回事。CtrlL只是让终端界面清爽一点对话上下文还在如果你想让模型忘掉之前的讨论应该用/new新建会话或者用/compact压缩后再继续。3.4 允许opencode执行命令的边界设置opencode可以不只改文件还能执行终端命令比如跑测试、运行构建、查看git状态等。这对自动化非常有用但风险也在这里。如果完全放开万一它理解错了需求执行了类似清空目录、强制推送这类操作代价非常高。所以这个边界一定要在配置层面收紧。我的做法分两层第一层默认所有命令都经过确认它执行之前会在界面上显示即将运行的命令我等它弹出确认后再决定是否放行第二层对某些高频且安全的命令比如单元测试、查看当前改动、查看diff在配置里列为允许自动执行省去每次按确认键。对删除、强制覆盖、推送远端这一类命令我基本保持拦截询问状态。另外如果你在跑一个长时间任务尽量让opencode把命令分段执行而不是一次性拼接一长串命令。分段执行时你可以观察每一步的产出错了能及时打断。把它看作一个需要授权才能动手的实习生而不是完全放养。4. 把opencode接入真实项目工作流4.1 一个bug修复的标准循环我建议你第一次实际使用不要直接甩给它“重构整个模块”而是从一个小bug开始。先告诉它现象比如跑某个测试用例会得到一个断言失败同时给它测试文件路径和对应源文件路径。它读取代码后会先分析原因给出它计划执行的步骤然后开始运行测试复现问题、修改文件、再次运行测试。第一轮尽量不要让它直接改文件而是先让它输出排查思路。你可以追问“为什么你会认为是这里”如果它分析得靠谱再补一句“按这个思路改吧”。这样做的原因是模型在直接动手时偶尔会基于猜测去改而不是基于证据。让它先说思路能逼着它把推理过程暴露出来你也能及时纠偏。一旦修改完成它会把改动列成diff给你确认。我习惯在确认前先自己扫一遍看有没有改动到无关文件。opencode通常很听话但如果上下文太长可能会“顺手”改坏空格或者误删注释。确认后再允许它继续执行测试直到绿灯。4.2 自动提交与代码托管平台联动opencode可以帮你生成提交信息甚至执行提交动作。日常开发里我最常用的是让它“在完成修复后根据diff生成一条commit信息并提交到当前分支”。它会看当前改动和提交历史总结改动内容然后生成一句简短的描述。注意你需要在配置里允许它执行git相关的命令否则它只能给你信息不会动手。如果你配置了代码托管平台还可以让它创建变更请求。这个功能对独立开发者特别方便改完分支后直接让opencode把分支推送到远端并创建一个变更请求不用再专门打开网页点按钮。需要留意的是首次授权它访问托管平台时通常会涉及一个Token不要把这个Token写进代码仓库建议放到环境变量并通过api_key_env方式引用。我自己的原则是提交信息可以交给它生成但合并到主干这个动作我永远手动操作。因为合并本身往往涉及分支策略和权限控制让AI自动合并风险太大尤其在这个模型对项目整体架构理解有限的情况下。4.3 同时开多个任务并行处理使用opencode一段时间以后你会发现它可以同时开几个会话处理不同子任务。比如你在做一个大功能可以让会话A负责写接口会话B负责写前端页面会话C负责补测试用例。它们之间彼此独立只要工作在不同的文件里基本不会冲突。但需要注意如果两个会话同时修改同一个文件最后保存时就会互相覆盖。我遇到过一次两个会话几乎同时编辑同一个工具函数一个加了参数另一个改了内部实现结果最后提交时直接冲突。所以并行之前最好在需求里明确“各自负责哪些文件”或者干脆让其中一个专门负责该文件。小团队使用时也可以约定好文件划分避免两个人在同一个文件里反复打架。4.4 用项目规范文件约束行为让opencode长期稳定输出的关键是给它一套明确的项目规范。你可以在仓库根目录放一个类似AGENTS.md的说明文件里面写上项目结构、语言版本、测试命令、编码风格、提交信息格式等。opencode每次接收任务时会把这份规范作为背景信息然后按约束来行动。写规范文件时我建议用“要/不要”的形式而不是大段描述。比如“不要修改vendor目录下的文件”“测试命令统一用某个固定命令”“新函数需要补注释”。模型对这种命令式的文本理解更好。规定得越明确它出错的可能性越低。另外规范文件也可以用中文写。虽然不少模型对英文指令理解更好但你的项目成员如果都是中文交流写中文规范反而能保持一致性模型也能理解。如果你发现某个要求它总是做不到多半不是它不听话而是规范写得不够具体试着把它拆成可验证的条目。5. 模型选型与参数调优经验5.1 不同任务选不同模型opencode支持多模型你可以针对不同任务指定模型。我的经验是修bug、写测试、做代码审查这类明确任务用一个通用能力强的模型即可但如果你做深度重构、跨文件架构调整需要选推理能力更强的模型即使它速度慢一点、价格贵一点也值得日常问答、生成文档、补注释这类简单任务可以用更便宜或者本地模型来省成本。在你的配置里可以维护多套provider每个provider指定不同模型。opencode交互时可以用命令临时切换模型也可以用配置文件里的默认值。切换模型不会丢失当前会话但上下文可能无法完全兼容部分模型对历史消息的格式要求不同所以如果换了模型后发现上下文理解变差了最稳妥的办法是开一个新会话把核心需求再交代一次。5.2 温度、最大Token、并发这些参数怎么设模型接口通常都有温度、最大输出token等参数。opencode提供了配置项暴露这些参数。我一般会把温度调低比如0.2左右因为编程任务需要确定性和准确性不需要模型发挥创造力。如果你希望它给出多种不同实现方案再调高到0.7以上。最大输出token也需要关注。当任务复杂时如果上限太低它会回答到一半被截断还得你手动让它“继续”反而浪费上下文。我建议至少设置到模型支持的中高范围让它一次性写完。并发数指的是同时向模型发起的请求数opencode内部某些操作可能并行调用调大一点能提速但会放大API费用波动也更容易被服务商限流所以要根据自己的预算谨慎调整。5.3 系统提示词和角色设定的实际效果opencode里的系统提示词相当于你给它预设的“岗位说明”。比如你可以在配置里给它设定“你是一个资深前端工程师擅长组件库设计重视类型安全和可测试性”。它回答问题的角度和语言风格会明显贴近这个角色。不过别把系统提示词当成万能药。它只能约束行为方向不能保证输出质量。真正提升质量的是你在每个任务里给足上下文和验收标准。我用过最有效的一句话模板是“请先分析再给出修改计划最后动手。完成标准是xxx。”这个结构能给模型一个清晰的工作流比单纯说“帮我修一下”强得多。系统提示词也可以用来约束输出语言。比如要求“用中文解释代码注释用中英双语”这样它生成的答复风格更统一。5.4 私有化部署与成本控制如果你的项目代码很敏感不想把内容发送到外部模型服务商可以考虑在本地部署一个模型服务然后在opencode里把base_url指向本地。这样做的好处是数据不离开你的机器缺点是本地模型的能力往往不如云端大模型尤其是在处理超长上下文和复杂推理时差距明显。成本控制方面opencode本身是开源工具不收使用费你花的钱主要是模型API调用费。最容易失控的场景是让它处理一个自动化的长任务它可能反复调用文件操作、跑测试、重新分析错误这些操作会累积tokens。我建议在开始一个耗时任务前先在需求里说明“最多修改哪些文件”“最多尝试几次”并在配置里设置用量上限或者让opencode定期汇报已消耗的tokens。也可以先用本地小模型做骨架需要高质量分析时再切换到云端大模型。6. 常见问题与排查记录6.1 命令执行权限不够不少第一次用opencode的人会遇到它说“没有权限执行某个命令”或者明明让它跑测试它却只给出命令让你自己运行。这通常不是模型能力问题而是权限配置限制。opencode默认只允许执行白名单内的命令其他一律拒绝。你需要检查配置文件里的允许命令列表把常用的命令加进去或者临时切换到询问模式。需要注意的是放开权限命令列表时建议按“最小权限”原则来只放行你当前项目里真正需要的那几条。有个朋友图省事把命令列表设置成允许所有命令结果某一次它误把构建产生的临时目录当成了源码目录执行了清理命令虽然没删重要东西也够吓人的。6.2 上下文被撑爆回答开始胡言乱语上下文超限是Agent类工具最常见的问题。表现是前面的对话它还逻辑清楚到后半段开始重复、漏文件、甚至回答内容和当前任务无关。这是因为早期的信息在注意力机制里已经弱化或者直接超出了上下文窗口。解决办法是及时/compact。压缩上下文会把前面的多轮对话提炼成摘要释放空间。如果你发现压缩后它仍然丢失关键信息那就开新会话把任务核心重新描述一遍。为了防止这种问题我在任务一开始就尽量精简上下文只用给出关键文件不一开始把整个目录塞给它也让它在每次完成任务后小结一下变更点方便后面追溯。6.3 修改文件时和自己的工作产生冲突我在编辑器里可能正开着某个文件尚未保存此时opencode把它改了就会出现“一会保存把AI的改动覆盖掉”或者“AI看到的内容和我本地内容不一致”的问题。opencode读取和修改的是磁盘上的文件如果你的编辑器里有未保存的缓冲区它看不到。解决方法是在让它修改某个文件前先把编辑器里对应文件保存好。如果你不确定可以先在对话里问它“你看到的这个文件当前内容是什么版本”让它读出来和你本地对比。如果你的编辑器也做了自动保存冲突会少很多。但要注意opencode在写文件时不会自动帮你做版本合并如果这个文件同时被多个会话修改最终结果取决于最后一个写入者。所以并行任务的边界一定要划分清楚。6.4 Agent跑偏怎么让它停下来opencode在自动执行模式下可能会连续做多步操作如果你发现它越改越偏需要立刻打断。最快的办法是CtrlC取消当前操作它会停止正在执行的步骤并返回到对话输入状态。然后你可以用/undo撤销它刚才的文件改动回到上一个状态。我遇到过几次它“一条路走到黑”的情况原因是我的需求描述里有歧义它在某个分支上不断尝试错误方案。这时候不要硬让它继续先分析它当前改了哪些文件必要时用/new重开对话把需求说得更精确。在让它自动处理长任务时建议每完成一个文件修改就单独确认一次而不是一次性授权“全部改完”。虽然步骤多但能防止它带着错误走向更远的地方。7. 我的几条使用心得7.1 从最小改动开始我上手opencode时走过一段弯路一开始太信任它交给它的第一个任务就是“重构整个模块”结果上下文爆炸它改到一半自己也看不下去最后我不得不全部回退。后来我改成从小任务开始比如“把这个函数参数改成对象形式”“修复这个测试断言的错误”每次只碰一到两个文件。这样做还有一个额外好处模型在较小的上下文里表现明显更稳定几乎不会胡写。7.2 把opencode当“执行者”而不是“决策者”用了一段时间后我给它的定位是“执行者建议者”而不是“决策者”。它可以在方案讨论时给出建议但最终的架构决策、分支策略、合并操作我都会自己做。不是不信任它而是AI的上下文毕竟是有限的它理解的是你当前会话里给它看到的内容未必能看到整个项目的长期规划。你可以让它列方案对比但拍板的事别丢给它。7.3 一个小技巧先让它说计划再动手最后分享一个我每天都用的小技巧每个任务开始前先让opencode输出一段执行计划而不是直接让它改代码。计划里要包括“将读取哪些文件、修改哪些文件、运行什么命令、用什么标准判断完成”。等计划确认了再补一句“按计划执行”。这一步看起来多了半轮对话实际上能省掉大量无意义返工。我在实际使用中还有一个习惯计划文本如果超过5行我会让它把计划拆成两步先处理前半部分再处理后半部分。这样它的注意力更集中每一步的质量也更高。