快速上手

预计 20-30 分钟完成 OpenCode 安装和第一个 AI 编程任务（假设已安装 Node.js 并拥有 API Key），感受工程化 AI 编程的基础操作。

如果你已完成《5 分钟快速体验》（第 0 章）的安装步骤，可以直接跳到配置 Provider部分。

本章是全书动手的起点。之前两章讨论了“为什么要工程化“和“核心概念是什么“，现在到了“怎么做到“的时候。快速上手的定位是让读者在约 20 分钟内完成 OpenCode 的安装、Provider 配置、项目初始化和第一个有意义的任务（首次使用需注册 API 账户，约 5 分钟）。

读完这篇文章后，你不会成为配置专家，但会理解 OpenCode 的基本操作循环：配置 Provider、启动 Session、执行任务、查看结果。更重要的是，你会理解 /init 命令为什么是项目的“出生证明“，以及安全权限控制为什么是 Harness Engineering（驾驭工程） 的第一道防线。

⏱ 时间有限？先读这些： 安装 OpenCode → 配置 Provider → 第一个 Session → 安全配置

前置条件

在开始之前，你需要：

1. Node.js >= 18

   • npm 安装方式需要 Node.js 运行时
   • 使用 node --version 验证版本
   • 推荐使用 nvm 管理 Node.js 版本

2. 现代终端模拟器

   • 跨平台：WezTerm、Alacritty
   • macOS/Linux: Ghostty、Kitty、iTerm2
   • Windows：Windows Terminal、PowerShell

3. 至少一个 LLM Provider 的访问权限

   • OpenCode Zen 账户（推荐新手，在 https://opencode.ai/auth 注册）
   • 或 Anthropic（API Key 以 sk-ant-api03- 开头） / OpenAI（API Key 以 sk-proj- 开头） / Google API Key
   • 或 GitHub Copilot 订阅

安装 OpenCode

OpenCode 支持多种安装方式，覆盖 macOS、Windows、Linux 三大平台。选择适合你系统的安装方法即可。

安装流程图

下图展示了 OpenCode 的安装流程选择分支，覆盖 macOS、Windows、Linux 三大平台的安装方式。

%%{init: {'theme':'base', 'themeVariables': {'primaryColor':'#4A90D9', 'secondaryColor':'#50C878', 'tertiaryColor':'#FF9F43'}}}%%
flowchart TB
    subgraph macOS
        A1[Homebrew] --> B1["brew install opencode"]
        A2[官方脚本] --> B2["curl -fsSL https://opencode.ai/install | bash"]
        A3[npm] --> B3["npm install -g opencode-ai"]
    end
    
    subgraph Windows
        C1[Chocolatey] --> D1["choco install opencode"]
        C2[Scoop] --> D2["scoop install opencode"]
        C3[npm] --> D3["npm install -g opencode-ai"]
        C4[WSL 推荐] --> D4[使用 Linux 安装脚本]
    end
    
    subgraph Linux
        E1[官方脚本] --> F1["curl -fsSL https://opencode.ai/install | bash"]
        E2[Arch Linux] --> F2["sudo pacman -S opencode"]
        E3[npm] --> F3["npm install -g opencode-ai"]
    end
    
    B1 & B2 & B3 & D1 & D2 & D3 & D4 & F1 & F2 & F3 --> G[验证安装]
    G --> H["opencode --version"]
    H --> I{显示版本号?}
    I -->|是| J[安装成功]
    I -->|否| K[排查问题]

macOS 安装

方式一：Homebrew（推荐）

brew install opencode

Homebrew 官方 formula 在 Homebrew 主仓库中维护，开箱即用。如需更新频率更快的官方 tap，可使用 brew install anomalyco/tap/opencode。

方式二：官方安装脚本

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

方式三：npm 全局安装

npm install -g opencode-ai

中国大陆用户可通过 npm config set registry https://registry.npmmirror.com 加速 npm 安装（使用 opencode-ai 包）。

Windows 安装

推荐：使用 WSL

为了获得最佳体验，建议在 Windows 上使用 WSL（Windows Subsystem for Linux）。WSL 提供更好的性能和完整的 OpenCode 功能兼容性。

# 在 WSL 中使用官方安装脚本
curl -fsSL https://opencode.ai/install | bash

方式一：Chocolatey

choco install opencode

方式二：Scoop

scoop install opencode

方式三：npm 全局安装

npm install -g opencode-ai

方式四：mise

mise use -g opencode

Linux 安装

方式一：官方安装脚本（推荐）

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

方式二：Arch Linux

# 稳定版
sudo pacman -S opencode

# 最新版（从 AUR）
paru -S opencode-bin

方式三：npm 全局安装

npm install -g opencode-ai

方式四：Docker

docker run -it --rm ghcr.io/anomalyco/opencode

方式五：mise

mise use -g opencode

桌面应用 (Beta): OpenCode 现提供桌面应用，支持 macOS、Windows、Linux。从 opencode.ai/download 下载。

验证安装

安装完成后，运行以下命令验证：

opencode --version

如果显示版本号（v1.17.x 或更高版本），说明安装成功。

如果遇到 command not found 错误，请检查：

1. 安装路径是否在系统 PATH 中
2. 是否需要重启终端
3. 是否有权限执行该命令

常见安装问题

配置 Provider

OpenCode 支持 75+ 种 LLM Provider，你可以根据现有订阅或 API 访问权限选择最适合的方式。以下是三种最常见的配置方式。

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

OpenCode Zen 是由 OpenCode 团队提供的模型清单，这些模型已经过测试并验证可与 OpenCode 良好配合。这是最省心的选择，适合刚接触 AI 编程的用户。

配置步骤：

1. 在 OpenCode TUI 中运行 /connect 命令：

/connect

2. 在 Provider 列表中选择 OpenCode Zen

3. 浏览器会自动打开 opencode.ai/auth，完成登录并填写账单信息

4. 复制生成的 API Key

5. 回到终端，粘贴 API Key：

┌ API key
│ sk-proj-xxxxx
│
└ enter

6. 运行 /models 查看可用模型列表：

/models

提示：如果浏览器未自动打开，请手动访问 https://opencode.ai/auth 完成认证。

优势：

• 无需分别注册多个 Provider
• 模型已经过 OpenCode 团队验证
• 统一计费，简化管理
• 支持多种高质量模型

方式二：自有 API Key

如果你已有 Anthropic、OpenAI 或 Google 的 API Key，可以直接配置使用。

⚠️ 重要提示：Anthropic 禁止使用 Claude Pro/Max 订阅 OAuth 方式访问 OpenCode（Jan 2026）。请使用标准的 Anthropic API Key（按 token 计费）来配置。

Anthropic Claude 配置：

1. 运行 /connect 命令：

/connect

2. 选择 Anthropic

3. 输入你的 Anthropic API Key（以 sk-ant-api03- 开头）

4. 运行 /models 选择模型

OpenAI GPT 配置：

1. 运行 /connect：

/connect

2. 选择 OpenAI

3. 输入你的 OpenAI API Key（以 sk-proj- 开头）

Google Gemini 配置：

1. 运行 /connect：

/connect

2. 选择 Google

3. 输入你的 Google API Key

环境变量配置（推荐）：

你也可以通过环境变量配置 API Key，避免在配置文件中存储敏感信息：

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"

# OpenAI
export OPENAI_API_KEY="sk-proj-xxxxx"

# Google
export GOOGLE_API_KEY="xxxxx"

在项目级配置文件 opencode.json 中引用：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

方式三：GitHub Copilot 登录

如果你已有 GitHub Copilot 订阅（Pro $10/月、Business $19/用户或 Enterprise $39/用户），可以在 OpenCode 中复用，无需额外购买 API。

注意：自 2026 年 6 月起，GitHub Copilot 采用基于用量的 AI Credits 计费模式。Copilot Pro 每月包含 $15 的 AI Credits，超出部分需额外付费（约 $0.01/credit）。

配置步骤：

1. 验证你的 Copilot 订阅状态：

访问 https://github.com/settings/copilot，确认状态为 Active。

2. 在 OpenCode 中运行 /connect：

/connect

3. 在 Provider 列表中搜索并选择 GitHub Copilot

4. OpenCode 会显示设备授权链接：

Please visit: https://github.com/login/device
And enter code: XXXX-XXXX

5. 打开浏览器，访问 https://github.com/login/device

6. 输入屏幕上显示的设备码（如 XXXX-XXXX）

7. 点击 “Authorize” 授权 OpenCode

8. 授权成功后，OpenCode 显示：

✓ Provider added successfully!

9. 运行 /models 查看 Copilot 提供的模型：

/models

可用模型示例：

注意：实际可用模型列表会随 GitHub Copilot 的更新而变化，请以 /models 命令输出为准。

注意事项：

• 部分高级模型（如 gpt-5.3-codex）可能需要 GitHub Copilot Pro+ 订阅
• 普通订阅可能只能访问部分模型
• 凭证存储在 ~/.local/share/opencode/auth.json，请勿提交到 Git

Provider 配置对比

注意：下文使用层级化模型名称标识模型在能力/成本谱系中的位置，具体映射请参考 OpenCode 官方文档的模型支持列表。

第一个 Session

完成安装和 Provider 配置后，让我们开始第一个 OpenCode Session。

启动 OpenCode

进入你的项目目录并启动 OpenCode：

cd /path/to/your/project
opencode

首次启动时，OpenCode 会显示一个终端用户界面（TUI），底部是输入框，上方是对话区域。

初始化项目：/init

/init 命令是 OpenCode 理解你项目的关键步骤。它会分析项目结构并生成 AGENTS.md 文件——这是项目的“出生证明“。

在 OpenCode 输入框中输入：

/init

OpenCode 会：

1. 扫描项目目录结构
2. 识别技术栈（语言、框架、工具）
3. 分析代码模式和约定
4. 生成 AGENTS.md 文件

AGENTS.md 示例：

# 项目名称

## 技术栈

- 语言：TypeScript
- 框架：React + Vite
- 测试：Vitest
- 包管理：pnpm

## 项目结构

- `src/components/` - React 组件
- `src/hooks/` - 自定义 Hooks
- `src/utils/` - 工具函数

## 常用命令

- `pnpm dev` - 启动开发服务器
- `pnpm build` - 构建生产版本
- `pnpm test` - 运行测试

## 编码规范

- 使用函数组件和 Hooks
- 组件命名使用 PascalCase
- 文件命名使用 kebab-case

重要提示： 应该将 AGENTS.md 提交到 Git。这帮助 OpenCode 理解项目结构和编码模式。

Plan 模式：提问和分析

OpenCode 有两种主要模式：Plan 模式 和 Build 模式。

• Plan 模式：只读，适合提问、分析、规划
• Build 模式：可以修改文件、执行命令

按 Tab 键切换模式。右下角会显示当前模式。

切换到 Plan 模式：

<TAB>

现在，尝试问几个关于项目的问题：

这个项目的认证流程是怎样的？

@src/api/index.ts 这个文件的主要功能是什么？

提示： 使用 @ 键可以模糊搜索项目文件，将其添加到上下文中。

Build 模式：执行第一个改动

当你准备好让 OpenCode 修改代码时，切换到 Build 模式：

<TAB>

尝试一个简单的任务：

在 README.md 中添加一个"快速开始"章节，说明如何安装和运行项目。

OpenCode 会：

1. 分析你的请求
2. 读取 README.md
3. 生成修改建议
4. 应用修改

撤销操作：/undo

如果修改不符合预期，可以使用 /undo 命令撤销：

/undo

OpenCode 会撤销最近的修改，并显示原始消息，让你可以调整提示词后重试。

提示： 可以多次运行 /undo 来撤销多个操作。

重做操作：/redo

如果你想恢复撤销的操作：

/redo

常用命令速查

以下是 OpenCode 最常用的命令：

快捷键：

安全配置

Harness Engineering 的第一条原则是可控。OpenCode 的权限系统让你精确控制 Agent（智能体） 能做什么、不能做什么。

权限级别

每个权限规则可以设置为三种级别：

推荐新用户的安全配置

对于新用户，我们强烈建议将 edit 和 bash 权限设为 ask，这样所有文件编辑和命令执行都需要你的确认。

在项目根目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "*": "ask",
    "edit": "ask",
    "bash": "ask"
  }
}

配置解释：

• "*": "ask" — 所有未明确配置的权限都需要确认
• "edit": "ask" — 所有文件编辑操作都需要确认
• "bash": "ask" — 所有 Bash 命令执行都需要确认

细粒度权限配置

你可以根据命令模式或文件路径设置更精细的权限：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git status": "allow",
      "git log*": "allow",
      "git diff*": "allow",
      "npm install*": "allow",
      "npm run*": "allow",
      "rm -rf*": "deny"
    },
    "edit": {
      "*": "ask",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

规则优先级： 最后匹配的规则生效。建议将通配符 * 规则放在前面，更具体的规则放在后面。

排除文件：.ignore

OpenCode 默认使用 .ignore 文件（ripgrep 格式）来排除不需要跟踪的文件：

# 环境变量
.env
.env.*
!.env.example

# 依赖目录
node_modules/
vendor/

# 构建产物
dist/
build/
out/

# 敏感配置
secrets/
credentials/
*.pem
*.key

# 数据库文件
*.db
*.sqlite

注意：也可以通过 opencode.json 中的 watcher.ignore 配置来排除文件。

默认安全行为

OpenCode 默认对以下情况采用保守策略：

• .env 文件默认需要确认（ask）
• doom_loop（重复调用检测）默认需要确认
• external_directory（访问项目外目录）默认需要确认

权限确认对话框

当 Agent 尝试执行需要确认的操作时，你会看到：

┌ Agent wants to edit file
│ File: src/components/Button.tsx
│ Action: Modify
│
│ [Once] [Always] [Reject]
└

选择：

• Once：仅允许本次操作
• Always：本次会话中允许所有类似操作
• Reject：拒绝操作

常见反模式

跳过安装前检查直接运行

现象：跳过 OpenCode 的安装依赖检查（如 Node.js 版本、Git 配置），直接运行 opencode 后遇到底层错误。

原因：OpenCode 依赖 Node.js 18+ 和 Git 2.23+ 等基础工具。高级功能（如 MCP 服务器）还需要 Python 环境。

对策：安装后运行 opencode --version 确认版本，检查 .env 中的 API Key 配置，第一个 Session 中使用 /init 完成项目初始化。

在单个 Session 中塞入过多上下文

现象：在一个 Session 中不断追加任务，上下文窗口膨胀后 Agent 响应质量急剧下降。

原因：每个 LLM 调用携带全部对话历史。上下文接近模型限制时，Agent 开始忽略早期指令，产生幻觉或重复回答。

对策：复杂项目使用任务分解或多个 Session。当 Agent 反应迟钝时，使用 /new-session 或重启 OpenCode 清理上下文。

常见错误与陷阱

模型配置缺失（MODEL_CONFIG_MISSING）

场景：首次启动 OpenCode，跳过 Provider 配置直接输入任务。

后果：Agent 无法调用 LLM，Session 无法启动，错误类似 No provider configured。

预防：启动前至少配置一个 Provider。OpenCode Zen 模式自动处理，自有 Key 用户需确保 OPENCODE_API_KEY 已设置。

MCP 服务器启动失败

场景：配置 MCP 服务器后，工具调用返回 Connection refused 或 Tool not found。

后果：依赖 MCP 的工作流（如数据库查询、文件操作）无法正常执行。

预防：使用 opencode mcp list 确认服务器已注册，再用 opencode mcp debug <server> 排查连接问题；检查 MCP 服务器路径和参数，确保可执行文件有运行权限。

适用场景与限制

OpenCode 适合从个人项目到中型团队的多种开发场景。个人开发者可用它替代传统 IDE 进行日常编码；团队可用它统一开发环境和工具链。

以下情况 OpenCode 可能不是最佳选择：项目代码量超过 100 万行且上下文窗口无法覆盖关键模块时，建议配合外部知识库使用；对延迟极度敏感的生产环境变更，建议先用传统工具调试后再用 OpenCode 执行；需要细粒度权限控制的企业环境，需要额外配置 oh-my-openagent 的安全策略。

OpenCode 的高级能力（如 Team Mode、7-Agent Pipeline）需要 OMO v4.0+ 配合。部分功能（如 MCP 桥接）需要 Python 环境。建议定期关注版本更新日志，了解功能变化。

小结

恭喜你完成了 OpenCode 的快速上手！让我们回顾一下学到的内容：

1. 安装：OpenCode 支持多平台安装，macOS 推荐 Homebrew，Windows 推荐 WSL，Linux 推荐官方脚本

2. Provider 配置：三种方式满足不同需求——OpenCode Zen 最省心、自有 API Key 最灵活、GitHub Copilot 可复用现有订阅

3. 第一个 Session：/init 初始化项目生成 AGENTS.md，Tab 切换 Plan/Build 模式，/undo 撤销操作

4. 安全配置：权限系统让你精确控制 Agent 的能力，新用户建议将 edit 和 bash 设为 ask

核心概念回顾

• AGENTS.md 是项目的“出生证明“：第一次 /init 建立项目知识库，告诉 Agent 项目是什么、用什么技术、怎么运行

• Provider 自由度意味着什么：不锁定任何模型提供商，可以根据场景/成本灵活切换

• 安全先行：Harness Engineering 的第一条原则是可控，权限控制是最基础的可控手段

下一步

• → OpenCode 配置深度解析 — 深入了解配置文件结构和高级选项
• → oh-my-openagent 集成 — 扩展 OpenCode 的能力
• ← 核心概念 — 回顾 Agent、Skill（技能）、Workflow（工作流） 基础