opencode开源终端AI编程助手实测：多模型接入与TUI交互

AI 编程助手这两年被卷得不成样子，光是终端里能跑的就有不少选择：某商业模型的官方命令行工具、老牌的开源 CLI 编程 agent，再加上各家 IDE 的插件，说实话选项多到让人犯困。但这里有个问题——大部分工具都有明显的绑定倾向：要么绑死在某家模型服务上，要么绑死在特定的编辑器和工作流里。我一直在找一个能在终端里跑、模型选择自由一点、还能自己掌控数据流向的开源方案，后来在技术社区里翻到一个项目：opencode。这个名字你搜“AI编程 opencode”大概率能直接找到仓库，它本质上是一个开源的终端 AI 编程 agent，用 TUI 交互，能接多种模型服务，也可以通过配置接入本地模型。我用它替换了之前一部分 IDE 里的 AI 补全和重构流程，已经把几个小项目完整跑通过。如果你像我一样，习惯键盘操作、不想被某个具体厂商的账号体系捆住，那这篇可以当作一份实测记录来参考。

1. opencode 到底是什么：一个能住进终端的 AI 编程 agent

先把它放到熟悉的位置里理解。这些年 AI 辅助编程大致走了三个阶段：第一阶段是IDE 里的补全插件，像 copilot 那种，你在写代码时帮你接下一句；第二阶段是对话式助手，能基于当前代码上下文回答“这段逻辑哪里有问题”；第三阶段就是 agent，它不只是“回答”，而是真的会自己看代码、改文件、跑命令、看报错、再改，直到完成你交给它的任务。

opencode 属于第三阶段，而且它把落点放在终端里，不做成臃肿的 IDE 插件。它的运行界面是 TUI，不是网页也不是图形窗口，你打开终端、进入项目目录、运行 opencode，就能看到类似聊天面板的交互界面，左边是会话列表，右边是对话内容。模型会读取你项目里的文件结构、Git 状态、甚至语言服务器给出的诊断信息，然后直接生成改动、执行命令。

我最初用它的动机很朴素：不想为了 AI 编程把自己的开发流程迁到一个陌生编辑器里。我日常用终端 + Neovim + Git 这套工作流已经很习惯了，IDE 插件对我来说是额外负担。opencode 的好处是它不强占你的工作台，只是一个“会坐在你旁边干活的人”，平时该敲键盘敲键盘，需要 AI 动手时才把它拉进来。

它的核心能力可以总结成几块：

• 多模型接入：它可以调用多种模型服务，既有常见的大模型 API，也可以配置本地模型运行时，换模型不用换工具。
• Agent 行为模式：它分为 Ask、Agent、Lazy 三种模式，分别对应“问问题”“动手改码”“尽量少打扰地自动完成”，后面我详细展开。
• 项目级上下文：它不只是看单个文件，而是会读取仓库结构、.gitignore、Git 暂存区等状态，知道项目整体大概是什么情况。
• 可自定义规则：通过项目里的 AGENTS.md 文件，你可以告诉它“这个项目的代码风格是什么”“哪些目录不许碰”，这相当于给它写了一份工作须知。

说实话，它不适合完全零基础的人。如果你连终端都没怎么用过，先去学两天基础命令行再来折腾要舒服得多。但如果你已经在用终端做开发，那它确实是把 AI 能力塞进现有工作流里的一条近路。

2. 安装与初始化：从零到能用的完整步骤

这一节我把从下载到配置成功的全过程拆开讲，每一步都会说清楚“为什么要这么做”，而不是只甩一个命令。

1.1 安装：一行脚本，但注意版本来源

opencode 的安装方式，官方仓库 README 里通常会给几种：curl 一行脚本、npm 包、Homebrew 等。我在 Linux 环境上用的是官方推荐的一行脚本，大致是这样的：

curl -fsSL https://opencode.ai/install | bash

执行完成后，shell 里就能直接用 opencode 命令了。macOS 用户也可以走 Homebrew，Windows 用户我建议用 WSL 再跑，原生支持度没有前两者好。

这里提醒一个坑：这个工具迭代很快，版本号的差异有时候挺大。如果你安装后遇到界面和文档对不上，别急着怀疑自己装错了，先看一眼版本：

opencode --version

如果太老或者太新，去仓库 Release 页面对比一下，该升级就升级。我自己踩过一次，旧版本对某类模型 API 的兼容有问题，升级以后就好了，什么都没改。

提示：安装类工具的一个通用原则——尽量从官方来源获取，不要用第三方整合包。开源项目被篡改投毒的新闻这几年并不少见，终端工具能直接执行代码，风险更是前移到了你机器上。

1.2 初始化配置：所有秘密都在 config.json 里

首次运行 opencode 之前，建议先执行初始化命令：

opencode init

它会生成一个默认配置文件，位置在~/.config/opencode/config.json。这个文件就是整个工具的灵魂，模型选谁、鉴权方式、行为偏好，全在这里。

我自己的配置长这样，删掉了敏感信息：

{ "$schema": "opencode.json", "provider": { "apiKey": "env:OPENCODE_API_KEY", "model": "gpt-4o" } }

这里env:OPENCODE_API_KEY的意思是：API key 不硬写在配置文件里，而是从环境变量OPENCODE_API_KEY读取。这样做很有必要——如果你用 Git 管理 dotfiles，或者把配置分享给别人，key 就不会被意外提交到仓库里。

如果你想接的不是默认模型服务，而是别的“兼容各类大模型HTTP接口”的服务，或者本地模型，那 provider 块里的地址和模型标识就要跟着改。opencode 的定位就是模型自由，它不会强制你用哪一家，这也是我选它而不是商业闭源工具的核心原因之一。

注意：不管用哪个模型服务，请确认它的 API 格式兼容 opencode 的要求。目前大多数服务都走标准的 Chat 补全接口，但少数本地模型框架需要额外开一层兼容转换，否则即使 key 正确也会报 404 或格式错误。

1.3 环境变量和 shell 集成

配置完 key，我建议把环境变量写进 shell 的配置里，别每次启动终端都手动 export 一遍。以 bash/zsh 为例：

export OPENCODE_API_KEY="你的key"

然后在当前终端重新 source 一下就行：

source ~/.bashrc

不少人会在这步卡住：明明配了 key，运行 opencode 却提示鉴权失败。原因极大概率是环境变量没生效，或者你开了多个终端窗口，只有其中某个读了新配置。检查方法很简单——在终端里输入echo $OPENCODE_API_KEY，能输出 key 就说明没问题，输不出就回去看配置。

1.4 走一遍冒烟测试

配置完成之后，进入任意一个项目目录，运行：

opencode

TUI 界面起来后，随便问一句“这个项目是做什么的？”，正常来说模型会基于当前目录的文件读一遍再回答你。这一步能跑通，整个工具的骨架就算搭好了。

3. 工作流核心配置：AGENTS.md、模式选择与上下文控制

opencode 真正拉开与其他工具差距的地方，不在于它能“聊天”，而在于你能通过配置把它的行为调教到适合自己团队和项目。这一节是我认为最值得细看的段落。

2.1 用 AGENTS.md 给 AI 写工作须知

opencode 会在项目里读取 AGENTS.md 文件，把它当作规则来源。这个概念很像我带新人的时候先给一份“新人手册”：告诉他这个项目用什么语言、目录怎么组织、测试命令是什么、哪些地方不能乱动。

如果你第一次打开一个空项目，可以直接在 opencode 里运行/init指令。它会自动分析当前目录的文件结构、已有代码风格、包管理方式，然后生成一份 AGENTS.md。我实际跑过几次，生成的初稿虽然不算完美，但骨架已经很能打了，你再手动补几条项目特有的约定就完事。

一个真实例子：我之前在一个 Python 项目里写了三条规则：

- 不要修改 tests 目录下的文件，除非用户明确要求。 - 运行测试必须使用 pytest，不要直接运行脚本。 - 代码注释使用中文，但变量名和函数名保持英文。

有了这三条之后，opencode 的行为明显从“乱改一通”变成“有章法地改”，尤其第三点，它真的做到了注释全用中文，而代码标识符还是标准英文。这个文件你完全可以提交进 Git 仓库，让全团队共享。也就是说，你一个人的调教结果能直接造福整个项目，这个性价比很值。

2.2 三种模式怎么选

opencode 的模式切换是我每天都在用的功能，快捷键是 Tab，可以在 Ask、Agent、Lazy 三个模式间轮换。我一个个说：

• Ask 模式：只问答，不碰代码。适合“帮我解释这段正则”“这个报错是什么意思”“为什么这个函数会内存泄漏”这类问题。它对代码库是有读权限的，能引用具体文件回答，但不会产生任何改动，零风险。
• Agent 模式：完全体。它自己会读文件、改文件、执行命令、看测试结果、来回迭代。适合“实现一个用户注册接口”“把这段逻辑重构一下并保证现有测试通过”这种需要动手的任务。
• Lazy 模式：这是 Agent 模式的降噪版。它会尽量自己完成所有步骤，只在几个关键节点停下来等你确认，而不是每改一个文件就问你一次。适合批量任务的场景，比如“给所有 util 函数补上注释”。

使用心得：刚开始用的人会习惯性全跑 Agent 模式，但很快就发现，很多时候你只是想知道“这个 bug 可能出在哪”，结果它已经动手改了十行代码。先切 Ask 问清楚，再切 Agent 让它做，这种“先问后做”的顺序能省掉大量无谓的上下文消耗。

2.3 限制 AI 的“自由意志”

AI agent 最大的风险就是“过于主动”。你让它修一个 bug，它顺手把相邻几个函数也重构了，这种行为在 opencode 里一定得提前遏制。我的做法有三条：

第一，在 AGENTS.md 里写明“只做用户要求的事，不要主动做额外优化”。这条看起来像废话，实际上对模型行为约束非常有效。

第二，用 Ask 模式做预检。改动前先让它输出一个“修改计划”，包括涉及哪些文件、改动要点是什么，你确认了再切 Agent 让它执行。计划本身哪怕只是几句话，也能把它的行为框住。

第三，改动完成后，用 Git diff 审阅。opencode 不会帮你 commit，所有改动都会留在工作区，你完全可以用：

git diff

清清楚楚看到它到底改了哪些文件、哪些行。这个习惯无论如何都不能省，AI 写代码虽然快，但代码还是要人工把关。

4. 实战：用 opencode 从零写一个图像处理 Demo

命令、配置说得再多，不如完整走一遍流程。我带一个实际的项目跑一遍 opencode，这样你能看到它到底是怎么工作的。注意，下面这个“某图像处理Demo”是我随手虚构的练手项目，代码本身很简单，重点看工作流。

3.1 项目初始化

我建了一个空目录，进入后运行 opencode，然后直接输入/init。

opencode 里显示的回应大概意思是：检测到一个空目录，建议先描述项目目标，再由它生成目录结构和 AGENTS.md。于是我输入了需求：

写一个 Python 图像处理 demo：给图片做高斯模糊，支持半径参数，使用 Pillow。

它随即创建了demo.py、requirements.txt，然后写了一份 AGENTS.md，里面标记了“使用 Pillow 库、入口函数是 main()、添加依赖需更新 requirements.txt”这几条。

这一步看起来很轻松，其实背后的上下文整理能力是关键。opencode 会结合你所在目录的实际文件状态来生成建议，不是凭空给一段代码。它对“项目现状”的感知，很多 IDE 插件都做不到这个粒度。

3.2 核心功能实现与验证

接着我让它继续实现具体逻辑。下面是简化后的实际对话过程，大模型输出的详细解释我省略了，只看动作：

我：“实现高斯模糊函数，允许传入 sigma 和半径。”

opencode 做了这样几件事：

• 读了一遍demo.py当前内容；
• 在文件里新增了gaussian_blur(image_path, output_path, radius=3, sigma=2.0)函数；
• 调用 Pillow 的ImageFilter.GaussianBlur(radius)实现核心效果；
• 顺手在if __name__ == "__main__"里加了一个命令行参数入口；
• 之后执行了python demo.py test.jpg out.jpg跑了一次。

这里让我意外的是：它真的会去执行命令，而不是把命令以“建议”的形式扔给我。执行完它还自己读了一遍输出，确认没有异常才报告完成。

3.3 遭遇 bug：一张全黑的图片

第一次测试看着“成功”了，但生成的 out.jpg 是一张全黑图片。我把这个现象反馈给它，它开始进入真正的“agent 式排查”：

它先读了demo.py里与保存图片相关的代码，发现我把像素值的处理函数写对了读入、模糊和保存的顺序，但问题很可能出在图片格式。Pillow 的高斯模糊对 RGB 图片有效，但如果原图是 CMYK 模式，模糊过程中会出现颜色通道错乱，保存后看起来就是黑的。

它随后在函数里加了模式转换：

image = Image.open(image_path) if image.mode != "RGB": image = image.convert("RGB")

重新执行测试，这次输出正常。

注意：让 AI 自己查 bug 是有前提的。它之所以能快速定位，是因为可以阅读源码、可以执行命令、能看到执行结果，这三件事缺一不可。如果你中途切断了它的“执行命令”权限，只让它读代码猜问题，它大概率会给你一个模棱两可的猜测。

3.4 这次的流程总结

这次实验从零到跑通，全程不到十五分钟。真实提效点有三个：文件生成不用手敲模板、函数实现不用查 API 文档、报错排查不用逐行读代码。但反过来也要承认：如果我对图像处理完全没概念，连全黑图片意味着“通道问题”都不知道，那我看到 AI 报排查结果时也无法判断它是否靠谱。所以工具提效的前提，是你自己得有一定的判断力。

5. 高频问题速查与避坑清单

这部分是纯经验题，我把我踩过、以及身边朋友经常问的问题全部列成速查表。内容比较多，先看表格再补充说明。

4.1 常见问题速查表

4.2 值得一说的问题排查思路

上面的表格里，我特别想展开讲两个“看起来很简单但很坑”的。

第一个是 token 消耗。opencode 每次发送请求时会带当前对话历史，你聊得越长，每次消耗越大，这是所有对话式 AI 工具的通病。很多人以为“这个工具太烧钱”，其实是自己用错了。我现在的习惯是：每完成一个小任务就开一个新会话，旧会话可以保留在旁边随时查看，但当前工作会话保持短而集中。这个习惯帮我省了至少一半的上下文费用。

第二个是”模型改了不该改的文件”。有一次，我让它给某个工具函数加注释，结果它顺手把同目录下的另外两个文件也改了。排查发现：它读取目录结构时，判断项目很小，觉得“一起改完更合理”。这就是 AGENTS.md 里没写清楚边界的结果。后来我在项目规则里加了一行：“只能修改用户明确提及的文件”。从那以后基本再没越界过。

6. 我的使用心得：什么时候该用它，什么时候别固执

到最后说说这个工具适合什么场景、不适合什么场景。说实话，很多工具评测只会讲“有多强”，但一个真实用户最该知道的是“在什么条件下它不顶用”。

先说不适合的场景：项目规模很大、结构一团乱、而且你还没来得及建好 AGENTS.md 规则的时候，不要让 opencode 自由发挥。它虽然能读文件，但对一个上万文件的仓库，它的上下文窗口是装不下的，行为会越来越像“摸象的盲人”，改这里漏那里。这种情况先用它做 Ask 模式的代码问答，把项目结构摸清楚了，再让它动手改局部。

再说适合的场景：中小型项目、任务边界清晰、流程重复度高的活，是它最舒服的区域。比如给一个函数写单元测试、实现一个独立模块、批量重命名变量、修复一个明确复现步骤的 bug，这类工作它做得又快又稳。你让它今天就写一个“带登录鉴权的 REST API demo”，它从目录结构到代码实现能一口气给你搭出一个开工骨架，你再往里补业务逻辑就行。

我个人实际跑下来的体会是：opencode 真正改变的不是“写代码的速度”，而是“从想法到可运行 Demo 的路径长度”。以前想法出来，如果觉得这个项目要做很久就不想碰；现在反正先让 AI 搭个雏形，看着能有东西跑起来，动力完全不一样。它把“开始”的门槛降低了非常多。

最后分享一个小技巧：多花半小时维护 AGENTS.md 是完全值得的。让 AI 一次性看十个文件不如让它先看一条写清楚的好规则。规则越精确，它犯的错越少，你审核代码用的时间就越少。工具能放大你的能力，但前提是你得给它画好边界。