OpenCode 安装与快速入门完全指南：从零搭建你的 AI 编程开发环境

OpenCode 安装与快速入门完全指南：从零搭建你的 AI 编程开发环境

引言

OpenCode 是一个开源 AI 编程助手，凭借 16 万 GitHub Star、900+ 贡献者和每月 750 万活跃开发者，已成为当前最受欢迎的 AI 编程工具之一。它支持在终端、桌面应用和 IDE 扩展三种模式下运行，兼容 75+ 大语言模型提供商，并且内置了对 LSP、MCP 等协议的支持。

如果你正准备开始使用 OpenCode，这篇指南将带你完成从安装、配置到首次使用的完整流程，让你在 10 分钟内搭建好 AI 编程开发环境。

系统要求

在开始之前，确保你的系统满足以下要求：

• 操作系统：macOS、Linux 或 Windows（推荐 WSL）
• 终端：推荐使用 WezTerm、Alacritty、Ghostty 或 Kitty 等现代终端模拟器
• Git：需要 Git 来管理对话历史中的文件变更
• Node.js（可选）：如果使用 npm 方式安装

如果你使用 Windows，强烈建议安装 WSL（Windows Subsystem for Linux），这能提供更好的兼容性和性能。

安装 OpenCode

OpenCode 提供了多种安装方式，你可以根据使用习惯选择最适合的一种。

一键安装脚本（推荐）

最简单的方式是使用官方安装脚本：

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

这个脚本会自动检测你的操作系统和架构，下载对应的二进制文件并配置到系统 PATH 中。

使用包管理器安装

如果你已经安装了 Node.js，可以通过 npm 全局安装：

npm install -g opencode-ai

其他 Node.js 包管理器也同样支持：

# 使用 Bun
bun install -g opencode-ai

# 使用 pnpm
pnpm install -g opencode-ai

# 使用 Yarn
yarn global add opencode-ai

macOS Homebrew

macOS 用户可以通过 Homebrew 安装：

brew install anomalyco/tap/opencode

建议使用官方 Tap 源以获取最新版本。Homebrew 官方仓库中的版本更新会稍慢一些。

Windows 安装

Windows 用户有多种选择：

# 使用 Chocolatey
choco install opencode

# 使用 Scoop
scoop install opencode

# 使用 npm
npm install -g opencode-ai

# 使用 Docker
docker run -it --rm ghcr.io/anomalyco/opencode

不过如前所述，WSL 方案仍然是最佳选择。

验证安装

安装完成后，运行以下命令确认是否成功：

opencode --version

如果输出了版本号，说明安装成功。

配置 AI 模型提供商

OpenCode 本身不提供 AI 模型，你需要连接一个或多个模型提供商。它支持 75+ 提供商，包括 Anthropic、OpenAI、Google、DeepSeek 等。

方式一：使用 OpenCode Zen（新手推荐）

OpenCode Zen 是官方维护的精选模型列表，所有模型都经过测试和验证。这是新手最省心的选择：

打开终端并启动 OpenCode：

```bash
opencode
```

输入 /connect 命令，选择 OpenCode Zen。

终端会显示一个链接，浏览器会自动打开 opencode.ai/auth 页面。

登录你的账户，添加账单信息，然后复制 API Key。

回到终端粘贴 API Key。

输入 /models 查看可用模型列表，选择你想要的模型即可。

方式二：连接自有模型提供商

如果你已有特定提供商的 API Key，可以直接配置。以 DeepSeek 为例：

# 在 TUI 中运行
/connect
# 选择 DeepSeek，然后粘贴你的 API Key
# 运行 /models 选择模型，如 DeepSeek V4 Pro

对于本地模型，可以通过 Ollama 或 LM Studio 等工具运行：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

方式三：使用现有订阅

如果你已经订阅了 ChatGPT Plus/Pro 或 GitHub Copilot，可以直接登录使用：

/connect
# 选择 OpenAI 后选择 "ChatGPT Plus/Pro"
# 浏览器将打开进行 OAuth 授权

初始化项目

配置好模型提供商后，导航到你的项目目录：

cd /path/to/your/project

启动 OpenCode：

opencode

运行初始化命令，让 OpenCode 分析项目结构：

/init

OpenCode 会扫描你的项目文件，了解代码结构和编码模式，然后在项目根目录生成一份 AGENTS.md 文件。这个文件包含了项目的技术栈、约定和规则，后续 OpenCode 会参考它来生成更符合项目风格的代码。

建议将 AGENTS.md 提交到 Git，这样团队其他成员也能共享这份规则配置。

首次使用实战

提问与代码理解

你可以像聊天一样向 OpenCode 提问。使用 @ 符号可以模糊搜索项目中的文件并作为上下文：

请解释 @src/auth/login.ts 中的认证流程是如何实现的

使用 Plan 模式添加功能

当需要添加新功能时，建议先让 OpenCode 制定计划。按 Tab 键切换到 Plan 模式：

我希望为用户添加密码重置功能。流程是：
1. 用户点击"忘记密码"
2. 输入注册邮箱
3. 系统发送带链接的邮件
4. 用户点击链接后设置新密码

请制定一个完整的实现计划。

OpenCode 会输出详细的实施计划，你可以检查并提出修改意见。确认无误后，再次按 Tab 切换回 Build 模式，让它开始编码。

快速变更

对于简单的修改，可以直接在 Build 模式下操作：

请把 @src/utils/format.ts 中的日期格式化函数改为支持国际化

撤销与重做

如果 OpenCode 的修改不符合预期，使用 /undo 可以撤销上一次变更：

/undo

OpenCode 会使用 Git 来回退文件变更。/redo 可以恢复被撤销的修改。这两个命令支持连续使用。

遇到问题怎么办

常见排查方法

查看日志：启动时加上 --log-level DEBUG 可以查看详细日志：

```bash
opencode --log-level DEBUG
```

模型不可见：运行 /models 之前先尝试刷新缓存：

```bash
opencode models --refresh
```

API Key 问题：使用 opencode auth list 查看已配置的密钥状态。

升级到最新版：

```bash
opencode upgrade
```

下一步：个性化定制

完成基础配置后，你可以根据个人喜好进一步定制 OpenCode：

• 更换主题：运行 /themes 选择或创建自定义主题
• 自定义快捷键：编辑 tui.json 中的 keybinds 配置
• 配置代码格式化：在 opencode.json 中配置 formatters，让 AI 生成的代码自动符合团队规范
• 添加 MCP 服务器：通过 opencode mcp add 添加外部工具集成
• 创建自定义命令：在配置中定义斜杠命令，一键执行常用操作

总结

本文从零开始，完整介绍了 OpenCode 的安装、配置和首次使用流程。只需要几分钟时间，你就可以搭建好 AI 编程开发环境。其核心流程可以概括为三步：安装命令行工具 → 配置模型提供商 → 初始化项目并开始对话。

OpenCode 强大的地方不仅在于它能写代码，更在于它提供了 Plan/Build 双模式、撤销/重做、LSP 集成等工程化能力，让 AI 真正成为开发工作流中的一环。接下来，你可以继续阅读本博客的 OpenCode 系列文章，深入了解各个高级功能的使用方法。