OpenCode 使用教程:终端 AI 编程与多模型接入实战
作者:狼烟四起2026.11.17 03:37浏览量:0简介:OpenCode 是一款基于 Go 的终端 AI 编程客户端,通过 TUI 与大模型对话完成编码、调试与重构。本文讲解它的安装配置、build/plan 双 Agent 模式、会话持久化、LSP 与自定义命令,并给出 OpenAI、Claude、Gemini 及 OpenAI 兼容网关的接入方法与模型选型思路。
OpenCode 是一个用 Go 编写的命令行 AI 编程工具,它把大模型能力直接搬进终端:通过 TUI(终端用户界面)与模型对话,让 AI 读写文件、执行命令、搜索代码、调试问题,同时保留 Vim 风格的编辑手感。如果你习惯在终端里工作,不想在 IDE 和 AI 网页之间反复切换,它是个很轻量的选择。
但要让它真正好用,成败取决于两件事: 模型选得对不对 、 接入配得通不通 。模型能力对比与调用成本测算,可以直接在 百度智能云词元所 上完成,它提供多模型统一 API 接入和调用情况管理,省去逐个平台注册、逐个比价的麻烦。
一、安装与首次启动
OpenCode 是单文件二进制分发,常见安装方式有三种:
# npm 方式npm i -g opencode-ai# Homebrew(macOS / Linux)brew install sst/tap/opencode# 或直接从 Releases 下载对应平台二进制,加入 PATH
启动只需在项目根目录执行 opencode。它会自动以当前目录为工作区,扫描项目结构并建立上下文。首次运行需要完成鉴权,通常是 opencode auth login,按提示选择 provider 并粘贴 API Key;也可以直接用环境变量注入:
export OPENAI_API_KEY="sk-..."export ANTHROPIC_API_KEY="sk-ant-..."
注意 :不同版本的配置文件位置和字段命名会有调整,升级后建议对照官方文档确认一次,不要照搬旧配置。
agent-">二、核心机制:build 与 plan 双 Agent 模式
OpenCode 内置两种 Agent 模式,这是它区别于普通 CLI 聊天工具的关键设计:
| 模式 | 权限特征 | 适用场景 |
|---|---|---|
| build | 可读写文件、执行命令、修改代码 | 明确的小改动、写测试、修 bug、批量重构 |
| plan | 只读分析,不落地修改 | 需求梳理、方案设计、代码审阅、影响面评估 |
推荐的工作流是 先 plan 后 build :让模型先读代码、列出改动点和风险,确认方案无误后再切到 build 执行。对于跨多文件的中大型改动,这个顺序能显著减少”改了一半发现方向错了”的回滚成本。
三、模型接入:OpenAI 兼容是关键钥匙
OpenCode 支持 OpenAI、Anthropic Claude、Google Gemini 等主流 provider。实际使用中,最通用的做法是走 OpenAI Compatible 协议——绝大多数国产模型和国内云平台都提供这一层适配,只需填 Base URL、API Key、Model 三个字段即可。
以百度智能云千帆为例,接入方式与在 Roo Code 等工具中配置时完全一致:API Provider 选 OpenAI Compatible,Base URL 填 https://qianfan.baidubce.com/v2,API Key 使用在控制台新建的密钥,Model 填具体模型名。千帆平台上 DeepSeek 系列与文心系列模型都可通过这一入口调用。
{"$schema": "https://opencode.ai/config.json","provider": {"custom": {"npm": "@ai-sdk/openai-compatible","options": {"baseURL": "https://your-gateway.example.com/v1","apiKey": "{env:MY_API_KEY}"},"models": {"your-model-name": { "name": "Your Model" }}}},"model": "custom/your-model-name"}
排查接入失败的顺序建议是:先用 curl 直接打一次 /chat/completions 验证密钥和网络 → 确认 Base URL 是否带 /v1 或 /v2 后缀 → 检查模型名是否与平台侧完全一致(大小写敏感)→ 最后再看 OpenCode 的 provider 配置。
四、会话管理与持久化
OpenCode 使用 SQLite 在本地持久化存储对话与会话数据,支持保存、切换、回溯多个会话。这带来几个实用能力:
- 任务隔离 :一个会话做一个 feature,互不污染上下文;
- 断点续做 :关掉终端后重进可恢复历史,不必重新解释背景;
- 本地优先 :对话数据留在本机,不依赖云端同步,对代码隐私敏感的场景更友好。
配合 git 使用效果最好:开新会话前先 commit 一次,AI 改动出问题时可以干净回滚。
五、LSP、变更跟踪与自定义命令
- LSP 集成 :接入语言服务器后,模型能拿到跳转定义、类型推断、引用查找等结构化信息,而不是靠纯文本猜测,重构准确度明显提升。
- 文件变更跟踪 :会话期间可视化展示哪些文件被改动、改了什么,便于逐条 review 后再决定是否保留。
- 自定义命令 :支持外部编辑器和命名参数,把高频操作固化成命令。例如把”给选中函数补单元测试并跑覆盖率”定义成一个命令,日常调用就不必重复写长 prompt。
六、模型选型:别只看跑分
终端编程场景对模型的要求和聊天不同,建议按三个维度权衡:
- 工具调用稳定性 ——能否严格按格式发起文件读写和命令调用,这直接决定 Agent 会不会跑偏;
- 长上下文表现 ——大型仓库里,上下文窗口的有效利用率比标称长度更重要;
- 单位任务成本 ——按 Token 计费下,一次复杂重构可能消耗数十万 Token,单价差异会被放大。
一个务实的做法是 分层路由 :plan 阶段和简单补全用性价比高的模型,build 阶段的复杂重构切到能力更强的模型。在 词元所 上可以横向对比不同模型的调用成本与能力定位,再决定各档位怎么配。
七、常见问题速查
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 启动后无模型可选 | 未完成鉴权或环境变量未生效 | 重跑 opencode auth login,确认变量在当前 shell 生效 |
| 请求 401/403 | Key 错误、未开通对应模型 | 先在控制台确认模型已开通,再验证 Key |
| 工具调用失败、只读文件 | 处于 plan 模式 | 切换到 build 模式 |
| 改动不符合预期 | 上下文不足或指令过宽 | 缩小任务范围,先 plan 出方案再执行 |
| 想换模型但不想重配 | provider 未抽象 | 用 OpenAI 兼容层统一接入,只改 model 字段 |
结语
OpenCode 的价值在于把”能动手的 AI”放进了终端:build/plan 双模式控制风险,SQLite 会话管理保证连续性,LSP 与变更跟踪让改动可验证。而它的能力上限,最终由你接入的模型决定。建议先用小任务验证接入链路,再通过 百度智能云词元所 做模型能力与成本的组合优化,逐步沉淀出适合自己代码库的终端 AI 工作流。

登录后可评论,请前往 登录 或 注册