OpenCode：BYOK 终端 Agent 完全上手指南

为什么需要 OpenCode：终端里的多模型 Agent 工作台

传统 AI 编程工具存在两个结构性约束。其一是模型绑定：Claude Code 只支持 Anthropic 模型，Codex CLI 面向 OpenAI 生态，一旦供应商限流、涨价或发布新模型，切换成本极高。其二是环境绑定：IDE 插件形态的工具要求你停留在特定编辑器内，无法覆盖 SSH 到服务器、在 CI 里批量执行、或在 tmux 会话中长驻运行等场景。对于管理多个项目的工程师来说，为不同项目准备不同工具显然不可持续。

OpenCode 的解法是把“Agent 运行时”与“模型供应商”彻底分离。它通过统一的 Agent 调度层，把同一套“读代码 → 规划 → 改文件 → 运行验证”流程，路由到你配置的任何模型上。你可以在一个会话中先用 Claude 处理复杂重构，再切换到 Gemini 或本地模型处理批量简单任务，密钥、成本、数据流向均由你控制。配合本地 Ollama 或 vLLM 端点，代码完全不出内网，满足金融、政企等数据合规场景。

与同类工具的气质差异在于：Aider 强调“git 优先的结对编程”，Claude Code 强调“Claude 深度集成”，而 OpenCode 强调的是“一个终端工作台，接入你所有的模型”。它是更接近“模型无关的 Agent 基础设施”的定位，因此在多模型策略和自动化集成上有天然优势。

安装与环境配置：3 步就绪

安装方式有三种，任选其一。macOS 用户推荐 Homebrew 方式；Linux 或非 brew 环境推荐 npm 全局安装；不想引入包管理器依赖时用官方安装脚本。注意 npm 包名是 opencode-ai，早期的 opencode 包名已被其他项目占用，装错会导致启动命令冲突。

配置阶段需要设置至少一个模型提供商的 API Key。OpenCode 通过环境变量读取密钥：Anthropic 用 ANTHROPIC_API_KEY，OpenAI 用 OPENAI_API_KEY，Gemini 用 GEMINI_API_KEY。设置后运行 opencode models 可确认哪些模型服务可用。

验证安装：运行 opencode --version 查看版本号；在任意项目目录直接运行 opencode 进入 TUI 界面，若能看到模型选择提示，说明安装与环境配置全部完成。

# 步骤一：安装（三选一）brew install sst/tap/opencode               # macOSnpm install -g opencode-ai                  # npm 全局（注意包名）curl -fsSL https://opencode.ai/install | bash  # 官方脚本 # 步骤二：配置密钥（至少一个）export ANTHROPIC_API_KEY=sk-ant-xxxxxxexport OPENAI_API_KEY=sk-xxxxxxexport GEMINI_API_KEY=xxxxxxexport OLLAMA_API_BASE=http://localhost:11434  # 可选：本地模型 # 步骤三：验证opencode --versionopencode models        # 列出可用模型服务opencode              # 进入交互式 TUI

快速上手：5 分钟跑通第一个修复任务

最小可用流程的思路是：在项目根目录启动 OpenCode → 选择或切换模型 → 用自然语言描述任务 → 审阅 Agent 的修改 → 确认应用。以下是完整操作路径：

1. 启动：进入项目根目录（如 ~/work/my-app），运行 opencode，等待 TUI 加载完成。

2. 选模型：输入 /models 打开模型选择列表，用方向键选中一个已配置的模型（如 claude-sonnet-4-20250514）并回车；未配置任何密钥时会提示你设置环境变量。

3. 派发任务：在底部输入框输入自然语言任务，例如 修复 test 目录下失败的单元测试，回车开始执行。Agent 会自主读取相关文件、规划改动、修改代码并尝试运行验证。

4. 审阅修改：Agent 每产生一个文件改动，TUI 会展示 diff（文件差异）。逐个查看改动是否符合预期，确认无误后应用保留；不满意的改动可直接让 Agent 返工。

5. 管理会话：输入 /session 查看会话列表，输入 /share 生成一个 opencode.ai/share/... 链接分享当前会话给协作者。

进阶技巧：在会话中随时输入 /model 热切换模型，无需重启；输入 /agent 可切换到自定义 Agent（如“只写测试”或“只做代码审查”）以约束行为。对于一次性、无需交互确认的任务（如清理日志代码），直接用非交互模式 opencode run "删除所有 console.log 调用" 即可，适合脚本调用。

# 非交互式运行 Agent 任务（适合脚本与自动化场景）opencode run "修复 src/utils.ts 中的类型错误"opencode run --model claude-sonnet-4-20250514 "为 README 补充安装章节"

核心能力详解：5 大支柱

支柱一：BYOK 多模型接入。 opencode models 列出所有可用模型服务，涵盖 Anthropic Claude（含 Opus/Sonnet/Haiku 系列）、OpenAI（GPT 系列）、Google Gemini、Ollama（本地模型）、Azure OpenAI 与 Amazon Bedrock。每个服务在配置文件中定义 provider 条目，可指定模型 ID、baseURL（API 基地址，指向自定义网关或本地推理服务）与额外参数。这意味着一个团队可以共享同一套 OpenCode 配置，但各自按任务类型选择模型，成本可见可控。

支柱二：Agent 自动执行模式。 OpenCode 内置 Agent 循环：接收任务后自动扫描相关文件、生成修改计划、逐文件实施改动、运行命令验证结果。它利用 LSP（Language Server Protocol，语言服务器协议，为编辑器提供代码语义分析的标准协议）语义理解代码结构，能准确识别符号引用与类型关系。默认配置下它会对改动自动 git diff，你只需在 TUI 中审阅确认。

支柱三：MCP 工具扩展。 MCP（Model Context Protocol，模型上下文协议）是 AI 工具接入外部系统的标准协议。OpenCode 内置 MCP 客户端，你可以在配置文件或 opencode mcp 命令中注册 MCP 服务器——包括本地命令启动的进程型服务器，以及远程 HTTP 型服务器。典型用途是接入文件系统操作、数据库查询、网页抓取等工具，让 Agent 具备“动手能力”而不仅是“改代码能力”。

支柱四：多会话管理与分享。 会话自动持久化到本地目录，关闭终端、重启机器后可用 /session 恢复；在 tmux 或新终端窗口中可以继续同一会话。/share 生成分享链接，协作者无需安装 OpenCode 即可在浏览器中查看完整对话与代码改动，这对远程协作和代码评审非常实用。

支柱五：终端体验定制。 支持 Vim 键绑定、多主题切换、自定义快捷键。更重要的是可以用 .mdprompt 文件定义自定义 Agent：在 prompt 文件中写清楚角色、行为约束与输出格式，然后通过 /agent 调用，让团队把标准化的编码规范沉淀为可复用的 Agent 指令。

生产部署与监控：从上线到运维

部署方式一：CI 流水线集成。 opencode run 非交互模式天然适合 CI：在 GitHub Actions、GitLab CI 或 Jenkins 中安装 OpenCode，设置 API Key 环境变量，然后执行 opencode run "修复 lint 错误并运行测试"。命令执行完毕后以退出码反馈成功与否，可与现有流水线门禁（gate）结合，实现“提交代码 → 自动 AI 修复 → 人工审阅 PR”的半自动流程。建议在 CI 中固定安装版本（如 npm i -g opencode-ai@0.2.0），避免 0.x 快速迭代带来的行为漂移。

部署方式二：本地服务模式。 opencode serve 可启动本地 HTTP 服务，供 VS Code 插件等前端接入；服务与 TUI 共享同一套配置和会话存储，适合团队内以服务化方式统一暴露 AI 编程能力。数据全程留在本地或你自己的服务器，不经过第三方云端（分享功能除外）。

可观测性。 每个会话在界面中实时显示 token 消耗与估算成本；完整日志写入本地日志目录（默认 ~/.local/share/opencode/log/），排查问题时按时间戳检索。opencode.json 支持关闭遥测上报，满足内网部署的隐私要求。生产环境建议将配置文件纳入版本管理，并在升级前查看 Changelog 确认配置 schema（配置结构）是否有破坏性变更。

<p class="para-label">避坑清单：</p>

<ul class=“dash-list“><li>npm 包名是 opencode-ai 而非 opencode：opencode 在 npm 上被另一项目占用，装错会导致命令冲突或启动失败，macOS 用户优先用 brew install sst/tap/opencode。</li><li>分享链接是公开的：/share 生成的链接任何拿到 URL 的人都能查看，提交分享前检查会话中是否包含密钥、内网地址或未公开代码。</li><li>0.x 版本迭代快、配置可能不兼容：升级前查看官方 Changelog，生产环境锁定版本号，并将 opencode.json 纳入版本控制以便回滚。</li><li>本地模型必须正确配置 baseURL：接入 Ollama/vLLM 时若省略 baseURL 或服务未启动，模型列表加载会超时报错，先 curl 验证本地推理端点可达再配置。</li><li>大仓库全仓扫描 token 消耗高：Agent 为理解上下文会读取多文件，超大仓库建议利用 .gitignore 排除无关目录，并在任务描述中限定文件范围（如”只改 src/api 目录”）。</li></ul>

版本迭代

OpenCode 于 2024 年 12 月由 SST 团队开源，2025 年处于 0.x 快速迭代期，几乎每月都有功能级更新。演进主线清晰：从“基础多模型 TUI 会话”到“会话分享与配置系统”，再到“MCP 与扩展生态”。项目仍未发布 1.0 稳定版，具体小版本号与发布日期以 GitHub Releases 为准。

AI 应用场景

常见误区

面试题

参考来源

• webpageOpenCode 官网产品入口、安装脚本与最新动态