OpenCode 使用指南

OpenCode 是一个开源的 AI 编程代理（AI Coding Agent），拥有超过 160K GitHub Star。支持 75+ 大模型提供商，可在终端、桌面应用和 IDE 中使用。

本文介绍在 Windows 11 环境下安装配置 OpenCode，并接入 DeepSeek V4 Pro 模型。

OpenCode 简介

Windows 11 安装

方法一：WSL（推荐）

官方推荐在 Windows 上使用 WSL 以获得最佳体验。

首先安装 WSL：

1

wsl --install

然后在 WSL 终端中安装 OpenCode：

1

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

项目位于 Windows 磁盘时，通过 /mnt/ 路径访问：

1
2

cd /mnt/d/github.com/my-project
opencode

方法二：Chocolatey

1

choco install opencode

方法三：Scoop

1

scoop install opencode

方法四：NPM

1

npm install -g opencode-ai

接入 DeepSeek V4 Pro

获取 API Key

1. 前往 DeepSeek 开放平台 注册并登录
2. 点击左侧菜单 API keys -> 创建 API key
3. 复制生成的 API Key

配置模型

在终端启动 OpenCode：

1

opencode

执行 /connect 命令连接 DeepSeek 提供商：

1

/connect

在列表中选择 DeepSeek，粘贴 API Key：

1
2
3

┌ API key
│
└ enter

执行 /models 命令切换模型：

1

/models

选择 deepseek-v4-pro 模型。

设为默认模型（可选）

在项目根目录创建 opencode.json 配置文件：

1
2
3
4

{
  "$schema": "https://opencode.ai/config.json",
  "model": "deepseek/deepseek-v4-pro"
}

基本使用

项目初始化

进入项目目录，启动 OpenCode 后先执行 /init，让 OpenCode 分析项目结构并生成 AGENTS.md：

1
2

cd /path/to/project
opencode

1

/init

AGENTS.md 是 OpenCode 理解项目的关键文件，记录架构、命令、规范等信息，建议提交到 Git。

模式切换

OpenCode 有 Plan 模式（计划）和 Build 模式（构建）两种工作模式，按 Tab 键切换。

推荐工作流：先在 Plan 模式下与 AI 讨论实现方案，确认后再切回 Build 模式执行。

常用命令

文件引用

在提示词中输入 @ 可以模糊搜索并引用项目中的文件：

1

请解释 @packages/utils/auth.ts 中的认证逻辑

拖拽图片

将截图或设计稿直接拖入终端窗口，OpenCode 会识别图片内容并加入上下文：

1
2

请参考这张设计稿实现用户设置页面
[拖拽图片到终端]

提示词技巧

让 AI 先出方案再动手

1
2

我们需要为 /settings 路由添加权限校验。
请先说明你的实现方案，不要直接修改代码。

提供充足的上下文

1
2

参考 @src/services/auth.ts 的实现方式，
为 @src/services/payment.ts 添加同样的日志记录逻辑。

描述越具体越好

像给初级开发者分配任务一样描述需求——说明目标、约束条件、期望的输出格式。

进阶配置

自定义 AGENTS.md

AGENTS.md 是项目级别的说明书，可以包含：

• 项目架构概览
• 常用命令（构建、测试、检查）
• 代码风格与命名规范
• CI/CD 流程说明

1
2
3
4
5
6
7
8
9
10
11

# AGENTS.md

## Commands
| Command | Does |
|---|---|
| `pnpm run build` | 构建项目 |
| `pnpm run test` | 运行测试 |

## Architecture
- 源码目录 `src/`，按功能模块划分子目录
- 使用 TypeScript 严格模式

模型参数调优

在 opencode.json 中可为特定模型配置推理参数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "deepseek": {
      "models": {
        "deepseek-v4-pro": {
          "options": {
            "reasoningEffort": "high"
          }
        }
      }
    }
  }
}

与其他模型对比

参考链接

• OpenCode 官网
• OpenCode 文档
• GitHub 仓库
• DeepSeek 开放平台
• Windows WSL 配置指南