OpenCode 与 Agent Skills 安装与使用指南

但是安装完成后，需要重启 opencode，skill 才会生效

三、opencode 安装

OpenCode 是一个开源的 AI 编程代理（AI coding agent），它可以作为终端界面、桌面应用或 IDE 扩展，在开发过程中提供协助。它的一大特点是模型无关性，允许连接来自不同供应商的多种 AI 模型，包括 Claude、GPT、Gemini 系列，甚至是本地部署的模型。

与许多集成在特定编辑器或服务中的 AI 工具不同，OpenCode 强调开放性和灵活性。它拥有一个活跃的开源社区，在 GitHub 上获得了超过 6 万个星标，由数百名贡献者共同维护。这种开放性意味着开发者可以拥有更高的自主权，根据自己的需求选择最合适的 AI 模型，而不被锁定在单一的生态系统中。

3.1 准备工作

3.1.1 终端模拟器

可以使用系统终端，也可以使用其它终端，官方推荐的终端包括：WezTerm (跨平台)、Alacritty (跨平台)、Kitty (Linux 和 macOS)、Ghostty (Linux 和 macOS)。

这些终端对图形渲染和文本样式有更好的支持，能确保 OpenCode 的界面清晰、功能完整。

Windows 11 系统中实测下来，直接用 PowerShell 效果就可以，但是需要提前对老版本的 PowerShell 进行升级。

3.1.2 AI 模型 API 密钥

OpenCode 本身是一个代理工具，它需要通过 API 连接到大型语言模型（LLM）才能工作。API 密钥（API Key）可以理解为访问这些模型服务的密码。因此，需要准备至少一个来自 LLM 供应商的有效 API 密钥。

对于初次接触的用户，OpenCode 提供了一个名为 Zen 的选项。它是由 OpenCode 团队筛选和基准测试过的一组模型，专为编程任务优化，可以提供稳定可靠的性能。当然，也可以选择连接自己的 Anthropic (Claude)、OpenAI (GPT) 或其他服务商的账户。

3.2 opencode 安装

3.2.1 快速安装

对于 macOS 和 Linux 用户，最简单直接的安装方式是使用官方提供的一键安装脚本。在终端中执行以下命令即可：

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

这个命令会从 opencode.ai 下载安装脚本并自动执行。脚本会智能地选择合适的安装路径，优先级顺序如下：环境变量 $OPENCODE_INSTALL_DIR 指定的目录；符合 XDG 基础目录规范的 $XDG_BIN_DIR 目录 (如果存在)；标准的 $HOME/bin 目录 (如果存在)；默认的回退路径 $HOME/.opencode/bin。

如果需要将 OpenCode 安装到特定位置，可以在执行命令前设置相应的环境变量。

3.2.2 使用包管理器安装

对于习惯使用包管理器的开发者，OpenCode 也提供了多种选择。

（1）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 

（2）Windows 安装

在 Windows 系统上，可以通过 Chocolatey 或 Scoop 这两个主流的包管理器进行安装。

使用 Chocolatey 的命令如下：

choco install opencode 

使用 Scoop 的安装命令则需要先添加 extras 存储桶：

scoop bucket add extras
scoop install extras/opencode 

（3）跨平台 Node.js 包管理器

如果你的开发环境中已经安装了 Node.js，那么使用 npm 或其他 Node.js 包管理器进行全局安装是一种方便的跨平台选择。

使用 npm：（注意可能需要更新 PowerShell）

npm install -g opencode-ai 

使用 pnpm：

pnpm install -g opencode-ai 

使用 Bun：

bun install -g opencode-ai

3.2.3 检查是否安装成功

在 PowerShell 中输入 opencode --version 检查是否已安装

3.3 桌面应用的安装与使用

除了终端版本，OpenCode 还提供了一个处于测试（Beta）阶段的桌面应用程序。它为不习惯在终端中工作的开发者提供了图形化界面，功能与终端版本保持一致。

可以直接从 OpenCode 的官方网站或 GitHub 的 Releases 页面下载对应系统的安装包。

对于 macOS 用户，同样可以使用 Homebrew Cask 来安装桌面版：

brew install --cask opencode-desktop 

下载并安装后，直接打开应用即可开始使用，后续的配置步骤与终端版类似。

四、opencode 配置

安装完成后，第一次运行 OpenCode 时需要进行一些基础配置，主要是连接 AI 模型。

4.1 大模型配置

在终端中进入一个项目目录，然后命令行输入 opencode 启动：

opencode 

启动后，会看到 OpenCode 的文本用户界面。此时，输入 /connect 命令并回车，它会弹出一个列表，让你选择要连接的 LLM 供应商。

对于新用户，选择 opencode (即 OpenCode Zen) 是最简单的开始方式。

选择后，按照提示在浏览器中打开授权链接，登录并获取 API 密钥，然后将密钥粘贴回终端即可完成连接。

连接成功后，还需要对当前项目进行初始化。在 OpenCode 界面中输入 /init 命令：

/init 

这个命令会让 OpenCode 分析当前项目的代码结构、依赖和编码风格，并在项目根目录下生成一个名为 AGENTS.md 的文件。这个文件存储了项目的上下文信息，能帮助 AI 代理更好地理解项目需求。建议将 AGENTS.md 文件提交到 Git 仓库中，以便团队成员共享和同步项目上下文。

此外，输入 /models 可以切换裸模型（基座模型）

4.2 基本用法

完成初始化后，就可以开始与 OpenCode 交互了。OpenCode 内置了两个核心代理（Agent），可以通过按 Tab 键在它们之间切换。build: 这是默认的代理，拥有完整的开发权限，可以读取文件、写入代码以及执行命令。plan: 这是一个只读的代理，用于分析代码和规划任务。它默认会拒绝修改文件，并在执行命令前征求许可，非常适合在探索不熟悉的代码库或规划复杂功能时使用。

例如，可以向它提问来理解代码库的某个部分。在提问时，可以使用 @ 符号来模糊搜索并引用项目中的文件：

How is authentication handled in @packages/functions/src/api/index.ts 

OpenCode 会读取并分析你引用的文件内容，然后给出相应的解释。这种交互方式使得理解和修改代码变得更加高效。至此，OpenCode 的基本环境已经搭建完毕，可以开始探索它在实际开发工作中的更多应用了。