以下是一份 OpenCode 从部署到使用的详细笔记，涵盖了各个关键步骤和常见问题。

OpenCode 部署与使用完全指南

一、OpenCode 是什么？

OpenCode 是一款开源、终端优先、模型中立的 AI 编程代理（Agent）。它与 ChatGPT 等对话式 AI 的本质区别在于：ChatGPT 是你问一句它答一句，代码需要你自己复制粘贴；而 OpenCode 是一个能理解项目结构、读取文件、规划方案、执行命令、审查差异，然后把改动直接写进代码库的 AI 代理。

核心特性

二、环境准备

2.1 Node.js 版本要求

OpenCode 依赖 Node.js 环境，版本需要 18 及以上。

验证当前 Node.js 版本：

node -v

如果版本过低，请前往 Node.js 官网 下载 18.x 或更高版本。

2.2 系统兼容性

• 支持系统：Windows、macOS、Ubuntu/CentOS 等 Linux 发行版
• Windows 用户注意：原生终端兼容性一般，官方推荐搭配 WSL2 子系统使用，可规避路径编码、权限报错等问题

三、安装 OpenCode

方式一：一键安装脚本（最推荐新手）

这是官方最推荐的入门方式，脚本会自动检测操作系统和架构，下载对应二进制文件并自动配置 PATH：

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

脚本执行结束后重启终端，即可使用 opencode 命令。

方式二：npm 全局安装（最常用）

如果你已有 Node.js 环境，这是最顺手的方式：

npm install -g opencode-ai

安装完成后验证：

opencode --version

出现版本号即表示安装成功。

⚠️ 常见问题：如果遇到 allow-scripts 警告，运行：

npm install -g --allow-scripts=opencode-ai

或通过配置永久允许：

npm config set allow-scripts=opencode-ai --location=user

方式三：包管理器安装

macOS/Linux 用 Homebrew：

brew install sst/tap/opencode

Windows 用 Scoop：

scoop install opencode

Windows 用 Chocolatey：

choco install opencode

Arch Linux：

sudo pacman -S opencode

方式四：Windows WSL（最稳定）

Windows 用户如遇到兼容性问题，推荐在 WSL 中运行：

# PowerShell 管理员模式
wsl --install

# 进入 WSL
wsl

# 一键安装
curl -fsSL https://opencode.ai/install | bash

安装完成后，在 WSL 中访问 Windows 文件：

cd /mnt/c/Users/你的用户名/项目路径
opencode

方式五：桌面版（Beta）

OpenCode 也提供了桌面版，可前往 opencode.ai/download 下载适用于 macOS 或 Linux 的安装程序。

四、配置 AI 模型（API Key）

OpenCode 本身是免费的，但你需要准备一个 AI 模型的 API Key。

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

OpenCode Zen 是官方提供的模型网关服务，自带免费层。

1. 在 TUI 中执行 /connect 命令
2. 选择 opencode
3. 前往 opencode.ai/auth 登录并获取 API Key
4. 粘贴 API Key 完成配置

免费层规则：

• 每天 100 次 免费请求
• 可无限制访问所有 Zen 精选模型
• 无需绑定信用卡

4.2 方式二：环境变量（最快上手）

macOS/Linux：

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."

# OpenAI GPT
export OPENAI_API_KEY="sk-..."

# Google Gemini
export GEMINI_API_KEY="your-key-here"

# DeepSeek
export DEEPSEEK_API_KEY="sk-..."

Windows PowerShell：

$env:ANTHROPIC_API_KEY = "your-key-here"

4.3 方式三：配置文件（推荐，更灵活）

在项目根目录或 ~/.config/opencode/ 下创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "apiKey": "你的API密钥"
    }
  }
}

4.4 方式四：opencode auth login 命令

交互式配置，支持所有提供商：

opencode auth login

按提示选择提供商并粘贴 API Key 即可。

查看已配置的凭证：

opencode auth list

凭证存储在 ~/.local/share/opencode/auth.json。

五、初始化项目

配置好 API Key 后，进入项目目录并启动 OpenCode：

cd /path/to/your/project
opencode

首次在项目中运行，建议执行初始化命令：

/init

这会分析项目结构并在根目录生成 AGENTS.md 文件，帮助 OpenCode 理解项目结构和编码模式。

注意：OpenCode 内部使用 Git 管理文件变更，因此项目需要是 Git 仓库。

六、核心使用指南

6.1 两种核心模式（按 Tab 键切换）

建议流程：先用 Plan 模式制定计划 → 确认后切换 Build 模式执行。

6.2 TUI 界面操作

启动 opencode 后会进入交互式终端界面（TUI）：

基本操作：

• 直接输入问题或需求
• 按 Tab 切换 Plan/Build 模式
• 输入 / 查看所有 Slash 命令

常用 Slash 命令：

6.3 内置工具

OpenCode 自带一系列内置工具，LLM 可通过这些工具在代码库中执行操作：

6.4 常用操作示例

让 AI 解释代码：

帮我解释一下这个项目的结构

让 AI 添加功能：

给 src/utils.ts 添加一个防抖函数

让 AI 修复 Bug：

修复 index.ts 第 42 行的类型错误

拖拽图片：可以直接将图片拖放到终端中，OpenCode 会扫描图片并将其加入提示上下文。

七、VS Code 集成

7.1 自动安装（推荐）

1. 打开 VS Code
2. 打开集成终端（Ctrl + `）
3. 运行 opencode——扩展会自动安装

7.2 手动安装

1. 在 VS Code 中按 Ctrl+Shift+X 打开扩展视图
2. 搜索 "OpenCode" 或 "sst.opencode"
3. 点击安装

7.3 快捷键

7.4 故障排除

如果扩展未能自动安装：

1. 确保是在 VS Code 的集成终端中运行 opencode
2. 确认 IDE 对应的 CLI 命令已安装：
   • VS Code：code 命令
   • Cursor：cursor 命令
   • VSCodium：codium 命令
3. 如未安装，按 Ctrl+Shift+P，搜索 "Shell Command: Install 'code' command in PATH"

八、进阶配置

8.1 自定义规则（AGENTS.md）

可以通过创建 AGENTS.md 文件为 OpenCode 提供自定义指令，类似于 Cursor 的规则功能：

/init

这会自动生成 AGENTS.md 文件。

8.2 自定义 Slash 命令

可以通过 OpenCode 配置或在 commands/ 目录中创建 Markdown 文件来新增自定义指令。

8.3 配置文件位置

• 项目级配置：项目根目录/opencode.json
• 全局配置：~/.config/opencode/opencode.json

8.4 更新 OpenCode

opencode update

九、常见问题

Q1: opencode 命令找不到？

Windows 用户：可能是 PowerShell 执行策略阻止了脚本运行。解决方法：

1. 切换到 CMD（命令提示符）运行
2. 或以管理员身份运行 PowerShell，执行：

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

Q2: npm 安装时报 allow-scripts 警告？

运行带 --allow-scripts 的命令：

npm install -g --allow-scripts=opencode-ai

Q3: Windows 上遇到兼容性问题？

强烈推荐使用 WSL2，这是 Windows 上最稳定的使用方式。

Q4: OpenCode 收费吗？

• OpenCode 本身：完全免费开源
• API 调用：取决于你使用的模型提供商（按量付费）
• OpenCode Zen：有免费层（每天 100 次请求），超出后需付费

Q5: 支持哪些模型？

支持 75+ 种模型提供商，包括 Claude、GPT、Gemini、DeepSeek、通义千问、Ollama 等。

十、快速参考卡片