OpenCode 是一个开源的 AI 编程代理（AI coding agent），它可以作为终端界面、桌面应用或 IDE 扩展，在开发过程中提供协助。它的一大特点是模型无关性，允许连接来自不同供应商的多种 AI 模型，包括 Claude、GPT、Gemini 系列，甚至是本地部署的模型。
与许多集成在特定编辑器或服务中的 AI 工具不同，OpenCode 强调开放性和灵活性。它拥有一个活跃的开源社区，在 GitHub 上获得了超过 6 万个星标，由数百名贡献者共同维护。这种开放性意味着开发者可以拥有更高的自主权，根据自己的需求选择最合适的 AI 模型，而不被锁定在单一的生态系统中。
准备工作
在安装 OpenCode 终端版本之前，需要确保开发环境满足一些基本要求。
终端模拟器
可以使用系统终端，也可以使用其它终端，官方推荐的终端包括：
- WezTerm (跨平台)
- Alacritty (跨平台)
- Kitty (Linux 和 macOS)
- Ghostty (Linux 和 macOS)
这些终端对图形渲染和文本样式有更好的支持，能确保 OpenCode 的界面清晰、功能完整。
AI 模型 API 密钥
OpenCode 本身是一个代理工具，它需要通过 API 连接到大型语言模型（LLM）才能工作。API 密钥（API Key）可以理解为访问这些模型服务的密码。因此，需要准备至少一个来自 LLM供应商的有效 API 密钥。
对于初次接触的用户，OpenCode 提供了一个名为 Zen 的选项。它是由 OpenCode 团队筛选和基准测试过的一组模型，专为编程任务优化，可以提供稳定可靠的性能。当然，也可以选择连接自己的 Anthropic (Claude)、OpenAI (GPT) 或其他服务商的账户。
安装 OpenCode
OpenCode 提供了多种安装方式，可以根据操作系统和个人偏好进行选择。
快速安装脚本
对于 macOS 和 Linux 用户，最简单直接的安装方式是使用官方提供的一键安装脚本。在终端中执行以下命令即可：
curl -fsSL https://opencode.ai/install | bash
这个命令会从 opencode.ai 下载安装脚本并自动执行。脚本会智能地选择合适的安装路径，优先级顺序如下：
- 环境变量
$OPENCODE_INSTALL_DIR指定的目录。 - 符合 XDG 基础目录规范的
$XDG_BIN_DIR目录 (如果存在)。 - 标准的
$HOME/bin目录 (如果存在)。 - 默认的回退路径
$HOME/.opencode/bin。
如果需要将 OpenCode 安装到特定位置，可以在执行命令前设置相应的环境变量。
使用包管理器安装
对于习惯使用包管理器的开发者，OpenCode 也提供了多种选择。
macOS 与 Linux 安装
在 macOS 和 Linux 系统上，Homebrew 是一个非常流行的包管理器。OpenCode 提供了两种 Homebrew 安装方式，它们的更新频率有所不同。
推荐使用 OpenCode 官方维护的 tap，因为它总能获取到最新的版本：
brew install anomalyco/tap/opencode
也可以使用 Homebrew 官方仓库中的配方，但它的更新可能会有延迟：
brew install opencode
对于 Arch Linux 用户，可以通过 Paru 从 AUR 安装：
paru -S opencode-bin
Windows 安装
在 Windows 系统上，可以通过 Chocolatey 或 Scoop 这两个主流的包管理器进行安装。
使用 Chocolatey 的命令如下：
choco install opencode
使用 Scoop 的安装命令则需要先添加 extras 存储桶：
scoop bucket add extras
scoop install extras/opencode
跨平台 Node.js 包管理器
如果你的开发环境中已经安装了 Node.js，那么使用 npm 或其他 Node.js 包管理器进行全局安装是一种方便的跨平台选择。
使用 npm：
npm install -g opencode-ai
使用 pnpm：
pnpm install -g opencode-ai
使用 Bun：
bun install -g opencode-ai
检查是否安装成功
输入 opencode --version 检查是否已安装
桌面应用的安装与使用
除了终端版本，OpenCode 还提供了一个处于测试（Beta）阶段的桌面应用程序。它为不习惯在终端中工作的开发者提供了图形化界面，功能与终端版本保持一致。
可以直接从 OpenCode 的官方网站或 GitHub 的 Releases 页面下载对应系统的安装包。
| 平台 | 下载文件 |
|---|---|
| macOS (Apple Silicon) | opencode-desktop-darwin-aarch64.dmg |
| macOS (Intel) | opencode-desktop-darwin-x64.dmg |
| Windows | opencode-desktop-windows-x64.exe |
| Linux | .deb, .rpm, 或 AppImage |
对于 macOS 用户，同样可以使用 Homebrew Cask 来安装桌面版：
brew install --cask opencode-desktop
下载并安装后，直接打开应用即可开始使用，后续的配置步骤与终端版类似。
首次配置与初始化
安装完成后，第一次运行 OpenCode 时需要进行一些基础配置，主要是连接 AI 模型。
在终端中进入一个项目目录，然后启动 OpenCode：
opencode
启动后，会看到 OpenCode 的文本用户界面。此时，输入 /connect 命令并回车，它会弹出一个列表，让你选择要连接的 LLM 供应商。
对于新用户，选择 opencode (即 OpenCode Zen) 是最简单的开始方式。选择后，按照提示在浏览器中打开授权链接，登录并获取 API 密钥，然后将密钥粘贴回终端即可完成连接。
连接成功后，还需要对当前项目进行初始化。在 OpenCode 界面中输入 /init 命令：
/init
这个命令会让 OpenCode 分析当前项目的代码结构、依赖和编码风格，并在项目根目录下生成一个名为 AGENTS.md 的文件。这个文件存储了项目的上下文信息，能帮助 AI 代理更好地理解项目需求。建议将 AGENTS.md 文件提交到 Git 仓库中，以便团队成员共享和同步项目上下文。
基本用法概览
完成初始化后，就可以开始与 OpenCode 交互了。OpenCode 内置了两个核心代理（Agent），可以通过按 Tab 键在它们之间切换。
- build: 这是默认的代理，拥有完整的开发权限，可以读取文件、写入代码以及执行命令。
- plan: 这是一个只读的代理，用于分析代码和规划任务。它默认会拒绝修改文件，并在执行命令前征求许可，非常适合在探索不熟悉的代码库或规划复杂功能时使用。
例如，可以向它提问来理解代码库的某个部分。在提问时，可以使用 @ 符号来模糊搜索并引用项目中的文件：
How is authentication handled in @packages/functions/src/api/index.ts
OpenCode 会读取并分析你引用的文件内容，然后给出相应的解释。这种交互方式使得理解和修改代码变得更加高效。至此，OpenCode 的基本环境已经搭建完毕，可以开始探索它在实际开发工作中的更多应用了。
开发必备：API 全流程管理神器 Apifox
介绍完上文的内容，我想额外介绍一个对开发者同样重要的效率工具 —— Apifox。作为一个集 API 文档、API 调试、API 设计、API 测试、API Mock、自动化测试等功能于一体的 API 管理工具，Apifox 可以说是开发者提升效率的必备工具之一。
如果你正在开发项目需要进行接口调试，不妨试试 Apifox。注册过程非常简单，你可以直接在这里注册使用。
注册成功后可以先看看官方提供的示例项目，这些案例都是经过精心设计的，能帮助你快速了解 Apifox 的主要功能。
使用 Apifox 的一大优势是它完全兼容 Postman 和 Swagger 数据格式，如果你之前使用过这些工具，数据导入会非常方便。而且它的界面设计非常友好，即使是第一次接触的新手也能很快上手，快去试试吧！
