先从一个真实的场景说起。我在终端里改一个 Python 服务突然想查一段正则为什么匹配不上顺手打开浏览器登录 ChatGPT 又觉得太重切到 IDE 里的 AI 插件又嫌上下文太乱。那时候我就在想要是有一个工具能在命令行里直接跟我对话、能读懂当前目录的代码、还能直接改文件那就省事太多了。后来我知道了 OpenCode试了一晚上第二天就把日常的 AI 编程辅助全迁了过去。所以这篇东西就是想把 OpenCode 的安装与使用从头到尾讲清楚让更多人少踩点坑。OpenCode 是一个开源的 AI 编程助手跑在终端里主打轻量、快速、模型无关。它跟 Cursor、Cline 这类工具解决的是同一个问题但思路完全不同。如果你平时用惯了 IDE 里的对话面板第一次看到 OpenCode 的终端界面可能会觉得简陋但用几天就会发现这种“少即是多”的设计反而让 AI 辅助编程真正融入了日常开发流。这篇内容适合三类人一是每天和终端打交道的后端开发者二是想尝试本地模型做编程辅助但不知道怎么接的人三是被 Cursor 这类闭源工具的订阅费烦到想换开源的玩家。下面我会从工具定位、三种安装方式、模型接入、实战用法到问题排查完整走一遍希望能帮你少走弯路。1. 先搞清楚 OpenCode 是什么再决定要不要装1.1 一个跑在终端里的 AI 编程助手OpenCode 的核心形态是一个 TUIText User Interface应用也就是在终端里渲染出一个交互界面有对话列表、消息流、文件 diff 预览但全程不需要离开命令行。它跟纯粹的 CLI 工具比如直接opencode 修复这个bug然后等输出还不一样它有自己的交互界面用方向键、回车、斜杠命令这套操作逻辑。我第一次打开它的时候界面让我想起终端里的邮箱客户端左边是会话列表右边是对话区底部是输入框。第一次用的人可能有点懵因为没有任何图形化的引导但上手成本其实很低。常用的操作就几个CtrlN新建会话、CtrlC中断输出、/呼出命令菜单、ShiftTab在输入框和输出框之间切换焦点。这套交互在官方文档里有完整说明但实际用下来记住这几个核心键位就够了其他都是锦上添花。1.2 模型无关一个客户端连接所有后端OpenCode 最吸引我的一点是模型无关的设计。它默认支持几十种模型供应商包括 Anthropic 的 Claude、OpenAI 的 GPT 系列、Google 的 Gemini也支持 Ollama 这类本地模型服务还有它自己的控制台免费额度。这意味着什么意味着你不需要为某个特定的 AI 编程工具锁定模型也不需要因为工具只支持特定厂商而被迫付费。你可以在同一个工具里随时切换日常问简单问题用免费模型写复杂重构用能力强点的模型完全离线时用本地模型。这种自由度和传统 IDE 里那种“装插件再配 API Key”的模式很不一样。模型无关的底层原因是 OpenCode 把模型调用抽象成了一层协议。它支持 Anthropic 的 Messages API、OpenAI 的 Chat Completions API也支持两者兼容的第三方中转服务。所有模型供应商都被拉平到同一个接口上统一处理所以切换模型对用户来说就是一次按键的事不需要改任何代码。1.3 适合谁用不适合谁用这个我得说实话OpenCode 不是所有人的菜。如果你不碰终端、只习惯在 Web 界面或完整 IDE 里操作那它的学习曲线会让你有点难受。但如果你是那种已经在终端里用 Git、用 Vim、用各种 CLI 工具的人OpenCode 几乎是零学习成本。还有一个更适合的场景是多项目并行开发。因为 OpenCode 是跟着当前目录走的你可以在~/project-a里启动一个会话再在~/project-b里启动另一个互相不干扰。相比 IDE 里那种项目切换的笨重感这种方式自然得多。2. 三种安装路径命令行、桌面版、VSCode 插件2.1 最快上手一行命令装 CLIOpenCode 的 CLI 安装方式很简单官方提供了两种途径。一种是直接跑一键安装脚本curl -fsSL https://opencode.ai/install | bash这个脚本会自动检测系统架构macOS 的 arm64 / x86_64Linux 的对应架构Windows WSL 环境然后下载对应二进制并安装到用户目录下。安装完成后脚本会提示你把 OpenCode 的可执行文件路径加入 PATH通常是在~/.opencode/bin或类似目录下。如果你用的是 macOS也可以直接用 Homebrew 安装brew install opencode装完以后验证一下opencode --version能看到版本号就说明装好了。这个验证步骤别省我见过太多人装完直接跑opencode结果命令找不到又排查半天最后发现是 PATH 没配好。2.2 桌面版不想碰终端的另一条路如果你还是想有个窗口化的界面OpenCode 也有桌面版。桌面版实际上是用 WebView 包了一层把终端里的 TUI 界面搬到了独立的桌面窗口里支持 macOS、Linux、Windows。它和 CLI 版共享同一个配置目录也就是说你在桌面版里创建的会话在 CLI 里也能看到反之亦然。安装桌面版的方式是去 OpenCode 的 GitHub Releases 页面下载对应的安装包。macOS 用户下载.dmgWindows 用户下载.exe或.msixLinux 用户下载.AppImage或.deb。下载后正常安装就行。不过说实话我用了一段时间桌面版最后还是回到了终端版。原因是桌面版本质上是同一套代码在窗口里运行却额外占用内存和渲染资源而它带来的唯一好处就是“看起来像个桌面应用”。如果你不是特别需要独立窗口直接用终端版反而更流畅。2.3 VSCode 扩展装不上、搜不到怎么办很多人在 VSCode 的扩展市场里搜索 OpenCode会遇到两个问题搜不到、或者搜到了但有多个同名扩展不知道选哪个。这里要说清楚一点OpenCode 官方在 VSCode 市场里其实有扩展但名字不一定是 OpenCode 本身有可能叫 “OpenCode AI” 或者由社区维护。更靠谱的做法是去官方文档或 GitHub 页面找扩展链接而不是在市场里盲目搜索。有些时候搜索不到是因为 VSCode 的扩展源设置问题可以检查一下是否启用了正确的市场源。安装完扩展后VSCode 里会多一个 OpenCode 的面板可以直接在 IDE 里打开终端界面也可以把当前选中的代码直接发送到 OpenCode 会话里。这个面板本质上还是在调 CLI所以前置条件仍然是命令行版已经安装成功。换句话说如果你在 VSCode 里打开 OpenCode 面板却报错找不到命令十有八九是 CLI 没装好或 PATH 没配好跟扩展本身没关系。2.4 安装完怎么验证装完以后别急着用建议先跑一个最简单的命令确认基础功能正常opencode run 说一句你好这会以非交互模式跑一次对话如果配置了可用的模型它会直接返回对话内容。如果没有配置任何模型它会提示你登录或添加模型供应商。这一步能很快定位是安装问题还是模型配置问题。3. 模型接入从控制台免费额度到 Ollama 本地推理3.1 控制台免费额度怎么开通OpenCode 有一个官方的控制台服务提供免费模型额度。这个免费层对初次体验的用户非常友好不需要绑信用卡只需要一个 GitHub 账号登录即可。具体操作是先运行opencode进入交互界面然后用方向键选中 “Console” 或类似选项按回车。它会弹出一个链接让你在浏览器里完成授权登录。登录成功后CLI 会自动获取对应的凭证然后你就可以用控制台提供的免费模型了。使用的时候有个细节需要注意控制台 provider 提供的免费额度是有限制的比如每天的消息数或每分钟的并发数。如果你只是日常小问题咨询基本够用但如果用来跑大型代码重构额度很快就见底了。另外控制台的免费额度只能在 OpenCode 应用内使用不能通过其他客户端或 API 方式调用这点我们要在下一节详细说。3.2 那个常见报错“free tier can only be used from within opencode”这个报错我在网上看到很多人遇到完整信息是error from provider (console): opencodes free tier can only be used from within opencode我第一次遇到这个报错时也很困惑明明就是在 OpenCode 里发起的请求怎么会提示“只能在 OpenCode 内使用”后来排查了半天才搞明白问题出在模型调用的源头。这个报错的意思是当前请求被识别为来自 OpenCode 之外的第三方客户端。最常见的触发场景是你在其他工具比如另一个 AI 客户端、脚本或程序里配置了console作为模型提供方然后通过 OpenAI 兼容接口或 Anthropic 兼容接口去调用 OpenCode 控制台的服务。控制台服务检查到调用来源不是 OpenCode 自身就拒绝了请求。还有另一种触发场景是在 OpenCode 内使用了自定义的 API Base URL指向了控制台服务。也就是说你通过opencode客户端发送请求但客户端配置的是兼容接口地址导致服务端认为这不是原生调用。解决办法是在模型配置里直接选择opencode作为 provider而不是手动填写baseURL。如果你的确是想在 OpenCode 内部使用免费额度确认方法其实很简单在交互界面的模型选择器里选中 Console 提供的模型不要手动改配置文件里的baseURL。如果是想在 OpenCode 之外用其他模型老老实实去申请对应厂商的 API Key别打控制台免费额度的主意。提示遇到 provider 报错时第一反应应该去看opencode.toml或opencode.json里的模型配置而不是怀疑是工具本身的 bug。绝大多数模型访问问题都出在 provider 配置环节。3.3 连接 Ollama 跑本地模型如果你对数据隐私要求高或者希望完全离线使用OpenCode 连接 Ollama 是个很好的方案。Ollama 是一个本地模型运行工具支持 Llama、Qwen、Mistral、Granite 等主流开源模型把模型下载到本地后用一条命令就能提供 OpenAI 兼容的 API 服务。OpenCode 连接 Ollama 的方式有两种第一种是直接在模型选择器里找 Ollama。如果你本机已经装了 Ollama 并拉取了模型OpenCode 会自动检测到http://localhost:11434上的 Ollama 服务并把可用的本地模型列出来选择就能用。第二种是手动在配置文件里指定。打开 OpenCode 的配置文件后面会说在哪里添加类似下面的内容[model_providers.ollama] name Ollama base_url http://localhost:11434/v1 api_key ollama添加后重启 OpenCode在模型选择器里就能看到 Ollama 下的模型了。注意Ollama 默认不校验 API Key但 OpenCode 要求配置里必须有这个字段所以随便填一个就行。实际体验下来本地模型的编程能力跟 Claude、GPT 仍然有差距但胜在免费、离线、数据不出本地。对于代码解释、正则生成、简单脚本这类轻量任务本地模型完全够用。我在没有外网的环境里用 Gemma 或 Granite 做日常咨询体验已经可以接受了。关于 Granite 的接入方式也是走 Ollama 这条路径先在 Ollama 里拉取 Granite 模型然后回到 OpenCode 选择即可。3.4 手动配其他模型供应商控制台免费额度和 Ollama 只是两种最省事的方案。如果你想用自己的 Claude、GPT 或 Gemini API Key配置方式也很清晰。运行opencode后按E键或/models打开模型配置界面按提示输入 API Key 即可。OpenCode 会自动识别密钥格式判断是哪个供应商的 Key然后把对应的模型列表加载出来。如果你想多账号切换比如公司一个 Key、个人一个 Key可以开两个配置文件通过环境变量OPENCODE_CONFIG指定使用哪一个。团队协作时也可以把配置文件提交到 Git 仓库让大家统一模型参数但注意不要把 API Key 提交上去。4. 从闲聊到真干活AGENTS.md、Skills 与对话归档4.1 AGENTS.md让 AI 懂项目规矩如果说模型是 OpenCode 的大脑那 AGENTS.md 就是 AI 的项目说明书。这个文件放在项目根目录用 Markdown 编写OpenCode 在每次会话启动时会自动读取它并把它作为上下文的一部分传给模型。这样模型就能了解项目的结构、代码风格、构建命令、注意事项等信息给出的建议也更有针对性。为什么这个文件很重要因为模型对项目的理解完全取决于上下文。你不告诉它这是一个用 FastAPI 写的服务它可能默认按 Flask 的写法给建议你不告诉它项目里有自动生成的 proto 文件不能动它可能某次“好心”帮你改掉。而 AGENTS.md 正是用来解决这些问题的。我的做法是每个项目维护一个精简的 AGENTS.md包含四个部分# 项目概述 这是一个内部数据平台的后端服务使用 FastAPI SQLAlchemyPython 3.11。 # 常用命令 - 本地启动uvicorn app.main:app --reload - 运行测试pytest tests/ -x -q - 代码格式ruff check . # 项目约定 - 禁止修改 migrations/ 目录下的已有迁移文件 - 所有接口必须使用 Pydantic 做请求校验 - 新增依赖需要通过 poetry add 添加 # 已知约束 - 单机部署暂不考虑分布式 - 数据库使用 PostgreSQL 13避免使用 JSONB 字段写完后放到项目根目录OpenCode 的每次会话都会自动带上这份说明。效果非常明显在不写 AGENTS.md 之前AI 给出的代码经常不符合项目风格写了之后第一次生成的代码就基本能直接进 PR。4.2 Skills给 AI 造趁手的工具Skills 是 OpenCode 的一个特色功能你可以把它理解成给 AI 装配的技能包。每个 Skill 是一个目录里面有一个SKILL.md文件描述这个技能什么时候用、怎么用还可以附带脚本文件让 AI 在执行任务时可以调用这些脚本。举个例子。我经常需要给新写的模块加单元测试就写了一个 Skill 专门干这个。SKILL.md 内容大致是--- name: add-tests description: 为指定 Python 模块生成 pytest 单元测试 --- # Add Tests Skill 当用户希望为某个模块添加测试时使用此技能。 ## 步骤 1. 读取用户指定的模块文件分析其类和函数 2. 识别需要测试的公共接口 3. 生成 pytest 测试文件保存到 tests/ 目录下 4. 运行 pytest --cov 验证测试覆盖率 ## 注意事项 - 测试代码风格遵循项目现有约定 - 不测试第三方库的行为 - 测试用例尽可能覆盖边界条件写完这个文件后放在~/.config/opencode/skills/add-tests/目录下不同系统路径略有差异然后在 OpenCode 里输入/add-tests app/services/user_service.pyAI 就会按照 SKILL.md 里的流程去执行任务。这个机制把“每次对话都要重复交代一遍要求”变成了“一句话调用完整流程”非常实用。除了自己写OpenCode 社区也有一批现成的 Skill 可以直接下载使用。安装方式很简单通常是把对应的 Skill 目录克隆下来放到 OpenCode 的 skills 目录里就行。社区里比较热门的 Skill 包括生成提交信息、代码审查、SQL 优化、Git 冲突解决等。4.3 代码改动怎么落盘归档对话存在哪OpenCode 不只是聊天工具它能直接改代码。当 AI 给出修改建议后你可以按a键接受全部改动或者按Tab在改动块之间切换逐块审查是否接受。接受后改动会直接写入文件。这种逐块确认的机制比 AI 直接改全部要安全得多我在实际使用中强烈建议用这种方式。但也要提醒一点OpenCode 的代码修改是基于当前文件内容和模型生成结果做的补丁式应用遇到文件特别大或者模型输出被截断时偶尔会出现应用失败的情况。碰到这种问题不要慌让模型重新生成或者手动复制改动内容。关于归档对话很多人问过“OpenCode 归档后去哪了”。默认情况下所有对话记录会存在本地的 SQLite 数据库里具体位置在配置目录下。macOS 是在~/.local/share/opencode/Linux 同理。如果你在那个目录里看到了类似opencode.db的文件那就是对话存档。OpenCode 本身没有提供官方的一键导出功能但你可以用 SQLite 浏览器打开这个数据库文件查看已有会话。如果你删了配置文件或数据库文件历史会话就彻底没了所以重要信息最好及时复制到项目笔记里。5. 用了一段时间后的几个坑与建议5.1 关于数据安全的几个原则用 OpenCode 这类工具数据安全是一个绕不开的话题。我的建议是分三层去考虑。第一层项目代码本身的敏感性。如果你的项目涉及非公开业务逻辑尽量不要使用外部模型服务或者至少确保公司允许把代码片段发送给对应模型厂商。第二层本地模型方案。对保密要求高的项目本地跑一个开源模型是最稳妥的代码根本不出本机。第三层配置信息保护。OpenCode 的配置文件里会保存 API Key 等敏感信息注意文件权限要设置成仅当前用户可读写不要因为追求方便把它提交到公共仓库。5.2 终端卡顿和输出丢失OpenCode 的 TUI 界面在大多数终端下表现不错但有两个场景会出问题。第一个是终端编码问题如果终端字符集不支持某些特殊符号界面里可能会出现乱码这种情况把终端的编码切到 UTF-8 就行。第二个是输出丢失当模型生成长文本时如果网络不稳定或服务端响应超时界面可能突然空白或者只显示一部分。这种时候先看是不是网络问题如果不是重启 OpenCode 一般能解决。还有一个容易被忽略的性能问题OpenCode 默认会把整个项目的文件索引加载一遍来计算上下文。如果你在一个很大的 monorepo 仓库里使用首次启动可能会明显卡顿。官方提供了一些配置项来控制扫描范围比如忽略node_modules、dist、.git等目录能显著提升启动速度。5.3 一套比较顺手的日常工作流最后分享一下我目前的日常使用流。每天早上到工位我会先开一个 OpenCode 会话把当天的任务列表粘过去让 AI 帮我拆解成步骤同时写好 AGENTS.md 让 AI 了解最新状态。开始写代码时遇到不确定的 API 就随手选中代码发送到 OpenCode 询问。写完一个模块后直接让 AI 生成测试再用预置的 Skill 跑一遍代码审查。整个过程中完全不离开终端。这个流程最妙的地方在于它可以跟 Git 工作流无缝衔接。对话摘要可以存在 Git message 里遇到问题可以先看历史会话记录不需要翻聊天记录。相比于 IDE 里装一堆插件这种极简、可组装的方式反而更适合我。我也理解不是所有人都愿意把日常工作都迁到终端里但我建议给 OpenCode 一个机会。先用控制台的免费额度体验两天觉得顺手了再接入自己的 API Key一步步来。它不一定能取代 Cursor 或 Copilot但在某些开发场景下效率提升是很明显的。装一个试试吧成本很低但可能改变你的开发习惯。