第二章：安装部署与环境配置

本章从零开始，一步一步带你完成 OpenCode 的安装、DeepSeek API Key 的获取与配置、配置仓库的克隆部署，以及最终的验证与常见问题排查。完成本章后，你将拥有一个完全可用的 OpenCode × DeepSeek 多 Agent 协作环境。

本章内容基于 znlgis/my-opencode-deepseek-config 仓库及 OpenCode 官方文档整理，实际命令与界面可能随版本更新略有变化，请以 opencode --help 与官方文档为准。

2.1 前置条件

在开始安装之前，请确保你的系统满足以下基本条件：

2.1.1 硬件与操作系统

Windows 用户若遇到兼容性问题，建议使用 WSL2（Windows Subsystem for Linux），体验更佳。

2.1.2 软件依赖

安装 OpenCode 前需要确认以下工具已就绪：

1. Git

OpenCode 的多项核心功能（会话快照、/undo、/redo、代码审查等）依赖 Git。执行以下命令确认已安装：

git --version
# 预期输出：git version 2.x.x 或更高

如未安装，请前往 git-scm.com 下载对应平台的安装包。

2. DeepSeek API Key

本配置方案基于 DeepSeek V4 三模型（Pro + Flash + Flash-Vision-Exp），需要有效的 API Key。详见 2.2 节。

3. OpenCode >= v1.18.x

DeepSeek provider 已被 OpenCode 内置支持，无需安装任何额外插件。本配置仓库要求 OpenCode >= v1.18.x（README 中明确标注）。如果之前安装过旧版本，建议先卸载再重新安装。

2.2 DeepSeek API Key 获取

2.2.1 注册与登录

1. 访问 platform.deepseek.com
2. 点击右上角「注册 / 登录」，使用手机号或邮箱完成注册
3. 登录后进入控制台

2.2.2 创建 API Key

1. 在左侧导航栏选择「API Keys」
2. 点击「创建 API Key」按钮
3. 为 Key 填写一个便于识别的名称（如 my-opencode）
4. 点击「创建」，页面会显示完整的 Key 字符串

注意：API Key 仅在创建时显示一次，请立即复制并妥善保存。如果丢失，需要重新创建新 Key。

2.2.3 充值说明

DeepSeek 采用按量付费模式，使用前需要账户中有余额：

• 进入「充值」页面，支持支付宝 / 微信支付
• 最低充值金额为 1 元人民币
• DeepSeek V4 采用按量付费，2026-08-16 起区分高峰 / 低谷时段定价（低谷约为高峰的一半）。以低谷价计（USD/百万 tokens）：Pro 输入 0.66 / 输出 1.98；Flash 输入 0.22 / 输出 0.66；Flash-Vision-Exp 与 Flash 同价。缓存命中读取价远低于输入价（Pro 0.022、Flash 0.007），是成本优化的关键杠杆
• 具体成本测算可参考仓库内 scripts/estimate-cost.js 脚本

提示：首次使用建议充值 10 元即可，正常情况下可使用很长时间。

2.2.4 安全提醒

• 绝对不要 将 API Key 提交到 Git 仓库
• 绝对不要 在公开场合分享你的 API Key
• 如果不慎泄露，请立即在 DeepSeek 控制台删除该 Key 并创建新 Key
• 本配置方案的 AGENTS.md 已将 .env 等敏感文件设为 deny 权限，防止误读

2.3 OpenCode 安装

2.3.1 一键安装脚本（推荐）

打开终端，执行以下命令：

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

安装脚本会自动检测操作系统并下载对应二进制文件。安装路径优先级：

1. $OPENCODE_INSTALL_DIR —— 自定义安装目录
2. $XDG_BIN_DIR —— 符合 XDG 规范的路径
3. $HOME/bin —— 用户二进制目录
4. $HOME/.opencode/bin —— 默认兜底

# 指定安装目录示例
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

2.3.2 包管理器安装

各平台的包管理器安装方式：

macOS（Homebrew）：

# 官方 tap（推荐，更新最及时）
brew install anomalyco/tap/opencode

# 或使用官方 Homebrew 公式
brew install opencode

Windows（Scoop / Chocolatey）：

# Scoop
scoop install opencode

# Chocolatey
choco install opencode

Linux（各发行版）：

# Arch Linux
sudo pacman -S opencode        # 官方源（稳定版）
paru -S opencode-bin           # AUR（最新版）

# 使用 npm / pnpm / yarn
npm install -g opencode-ai

# 使用 mise（版本管理器）
mise use -g opencode

2.3.3 验证安装

安装完成后，验证 OpenCode 是否正常工作：

opencode --version
# 预期输出：opencode x.x.x（版本号应 >= 1.14.24）

若提示找不到命令，请确认安装目录已加入系统 PATH，或重新打开终端。

2.4 配置 DeepSeek 模型连接

OpenCode 支持两种方式连接 DeepSeek：TUI 交互式配置（推荐）和环境变量。

2.4.1 方式一：TUI 交互式配置（推荐）

TUI 交互式配置最为直观，无需手动编辑任何配置文件。

步骤 1：启动 OpenCode TUI

opencode

此时终端会进入 OpenCode 的 TUI 界面。

步骤 2：连接 DeepSeek Provider

在 TUI 输入框中输入：

/connect

在弹出的 Provider 列表中选择 DeepSeek，然后粘贴你的 API Key。

步骤 3：选择模型

/models

在模型列表中选择 deepseek-v4-pro 作为主模型。系统会自动将 deepseek-v4-flash 设为小模型。

API Key 会自动持久化到 ~/.local/share/opencode/auth.json，下次启动无需重复配置。

2.4.2 方式二：环境变量

如果你更习惯通过环境变量管理密钥，可以在启动前设置 DEEPSEEK_API_KEY：

Windows（PowerShell）：

# 临时设置（仅当前会话有效）
$env:DEEPSEEK_API_KEY = "sk-your-key-here"
opencode

# 永久设置：将 DEEPSEEK_API_KEY 添加到系统环境变量
# 方式 A：系统设置 → 环境变量 → 新建用户变量
# 方式 B（PowerShell 管理员）：
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-your-key-here", "User")

Linux / macOS：

# 临时设置
export DEEPSEEK_API_KEY="sk-your-key-here"
opencode

# 永久设置：追加到 shell 配置文件
echo 'export DEEPSEEK_API_KEY="sk-your-key-here"' >> ~/.bashrc
# 或 (macOS zsh)
echo 'export DEEPSEEK_API_KEY="sk-your-key-here"' >> ~/.zshrc
source ~/.bashrc   # 或 source ~/.zshrc

2.4.3 Provider 配置参考

本配置方案的 opencode.jsonc 中通过 provider.deepseek.models 预设了 DeepSeek 三模型矩阵，并声明了各自的成本与思考开关：

{
  "model": "deepseek/deepseek-v4-pro",
  "small_model": "deepseek/deepseek-v4-flash",
  "provider": {
    "deepseek": {
      "models": {
        "deepseek-v4-flash": {
          "cost": { "input": 0.22, "output": 0.66, "cache_read": 0.007, "cache_write": 0.22 },
          "options": { "temperature": 0, "thinking": { "type": "disabled" } }
        },
        "deepseek-v4-flash-vision-exp": {
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "cost": { "input": 0.22, "output": 0.66, "cache_read": 0.007, "cache_write": 0.22 },
          "options": { "temperature": 0, "thinking": { "type": "disabled" } }
        },
        "deepseek-v4-pro": {
          "cost": { "input": 0.66, "output": 1.98, "cache_read": 0.022, "cache_write": 0.66 }
        }
      }
    }
  }
}

思考开关的默认值：Pro 的 thinking 默认开启（无需显式配置 thinking: { "type": "enabled" }），Flash 与 Flash-Vision-Exp 则在 provider 层显式关闭 thinking 并设 temperature: 0，这是 DeepSeek 官方（deepseek-harness）推荐的成本优化做法。options.thinking 是 provider 透传字段，OpenCode 会原样转发给 DeepSeek API。

模型 ID 命名规则：OpenCode 中模型的完整标识为 provider_id/model_id，即 deepseek/deepseek-v4-pro、deepseek/deepseek-v4-flash 和 deepseek/deepseek-v4-flash-vision-exp。modalities 声明了 vision-exp 支持图片输入，否则 OpenCode 会将其视为纯文本模型而拒绝 read_image 调用。

2.5 克隆配置仓库

本配置仓库在 opencode/ 子目录下包含 12 个 Agent 定义、25 个技能文件、全局规则（AGENTS.md）、插件配置（dcp.jsonc）和主配置文件（opencode.jsonc）。推荐克隆到任意位置后通过环境变量或符号链接指向 opencode/ 子目录即可使用。

2.5.1 方式一：克隆 + 环境变量（推荐，跨平台通用）

注意：本配置仓库的 agents/、skills/、AGENTS.md 等文件位于 opencode/ 子目录下，不能直接克隆到 ~/.config/opencode（否则会多嵌套一层目录）。推荐克隆到任意路径后通过环境变量指向 opencode/ 子目录。

步骤 1：克隆仓库

git clone https://github.com/znlgis/my-opencode-deepseek-config.git

步骤 2：设置环境变量

设置 OPENCODE_CONFIG_DIR 指向仓库内的 opencode/ 子目录：

Windows（PowerShell）—— 永久生效：

# 请将路径替换为你的实际克隆路径
[Environment]::SetEnvironmentVariable("OPENCODE_CONFIG_DIR", "D:\path\to\my-opencode-deepseek-config\opencode", "User")

Windows（PowerShell）—— 临时生效（仅当前会话）：

$env:OPENCODE_CONFIG_DIR = "D:\path\to\my-opencode-deepseek-config\opencode"
opencode

Linux / macOS —— 追加到 shell 配置文件：

# 请将路径替换为你的实际克隆路径
echo 'export OPENCODE_CONFIG_DIR="$HOME/path/to/my-opencode-deepseek-config/opencode"' >> ~/.bashrc
source ~/.bashrc

2.5.2 方式二：符号链接到全局配置目录

~/.config/opencode 是 OpenCode 的标准全局配置路径。通过符号链接将 opencode/ 子目录映射到标准路径：

Windows（PowerShell，需管理员）：

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config"
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode" -Target "D:\path\to\my-opencode-deepseek-config\opencode"

Linux / macOS：

mkdir -p ~/.config
ln -s /path/to/my-opencode-deepseek-config/opencode ~/.config/opencode

兼容性说明：该仓库的 opencode/ 子目录布局完全遵循 OpenCode 约定 —— agents/ 目录存放 Agent 系统提示、skills/ 目录存放可复用技能、AGENTS.md 作为全局规则文件。无论通过环境变量还是符号链接指向该目录，OpenCode 都能自动识别全部配置。

目录结构如下：

my-opencode-deepseek-config/
├── opencode/                   ← 配置目录（OPENCODE_CONFIG_DIR 指向此处）
│   ├── agents/                 ← 12 个 Agent 系统提示
│   │   ├── orchestrator.md     ← 主编排器（Flash，默认入口）
│   │   ├── solo.md             ← 单模型内联执行器（Pro，主 Agent）
│   │   ├── planner.md          ← 架构与规划（Flash）
│   │   ├── deep-worker.md      ← 重型实现（Pro）
│   │   ├── oracle.md           ← 深度代码分析（Pro，只读）
│   │   ├── reviewer.md         ← 代码审查（Pro，只读）
│   │   ├── consultant.md       ← 方案讨论与建议（Flash）
│   │   ├── ui-builder.md       ← 前端与 UI（Flash）
│   │   ├── explore.md          ← 代码库搜索（Flash，只读）
│   │   ├── librarian.md        ← 外部检索（Flash，只读）
│   │   ├── light-orchestrator.md ← 简单编辑（Flash）
│   │   └── vision.md           ← 多模态识别（Flash-Vision，只读）
│   ├── skills/                 ← 25 个可复用技能
│   │   ├── code-review/        ← 代码审查 + 严重度分级
│   │   ├── codemap/            ← 生成仓库结构图
│   │   ├── gh-cli/            ← GitHub CLI v2.100+ 参考
│   │   ├── git-master/         ← 高级 Git 操作
│   │   ├── git-release/        ← Tag 发布
│   │   ├── resolving-merge-conflicts/ ← 合并冲突解决
│   │   ├── handoff/            ← 会话压缩为交接文档
│   │   ├── opencode-config/    ← 编写和维护 OpenCode 配置
│   │   ├── office-docs/        ← Word/Excel 读写
│   │   ├── reflect/            ← 持续改进
│   │   ├── remove-deadcode/    ← 死代码检测与删除
│   │   ├── security-review/    ← 安全审查清单
│   │   ├── simplify/           ← 行为保持的代码简化
│   │   ├── spec-workflow/      ← 规约驱动开发
│   │   ├── verify-with-docs/   ← 检索优先 API 验证
│   │   ├── vision-prep/        ← 大图/PDF 预处理
│   │   ├── grilling/           ← 需求澄清提问
│   │   ├── wait-what/          ← 请求复述确认
│   │   ├── writing-for-agents/ ← 面向 Agent 的文档写作
│   │   ├── to-tickets/         ← 计划拆分为工单
│   │   ├── triage/             ← 工单分流
│   │   ├── diagnosing-bugs/    ← 系统化调试
│   │   ├── codebase-design/    ← 架构词汇表
│   │   ├── domain-modeling/    ← 领域术语表
│   │   └── grill-with-docs/    ← 组合式需求澄清
│   ├── AGENTS.md               ← 全局规则（所有 Agent 共享，218 行）
│   ├── opencode.jsonc          ← 主配置文件（17 条命令）
│   └── dcp.jsonc               ← DCP 智能压缩插件配置
├── scripts/                    ← 辅助脚本
│   ├── estimate-cost.js        ← 成本估算
│   ├── sync-config.ps1         ← 同步配置到 ~/.config/opencode
│   └── validate-jsonc.js       ← JSONC 校验
├── README.md                   ← 中文说明
├── README.en-US.md             ← 英文说明
└── LICENSE

2.5.3 Windows 路径注意事项

Windows 用户在克隆时可能会遇到以下问题：

• 路径过长：Git 默认不处理超过 260 字符的路径。如遇到 Filename too long 错误，以管理员身份运行：

  git config --system core.longpaths true
  

• 中文用户名目录：如果 Windows 用户名为中文（如 C:\Users\张三），$env:USERPROFILE 可能包含中文路径。大多数情况下兼容，但如果遇到编码问题，可以改用英文路径：

  git clone https://github.com/znlgis/my-opencode-deepseek-config.git D:\opencode-config
  $env:OPENCODE_CONFIG_DIR = "D:\opencode-config\opencode"
  

• PowerShell 执行策略：如果运行脚本时报 execution policy 相关错误，请先执行：

  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  

2.6 验证安装

完成以上步骤后，启动 OpenCode 验证所有组件是否正常加载：

opencode

在 TUI 中输入以下命令逐一验证：

2.6.1 验证模型连接

输入 /models，应显示当前模型为 deepseek/deepseek-v4-pro，小模型为 deepseek/deepseek-v4-flash。你可以手动切换模型来测试连接是否正常。

2.6.2 验证 Agent 加载

本配置仓库定义了 12 个 Agent（2 个主 Agent + 10 个子 Agent）。检查 Agent 列表确认所有 Agent 已被识别：

• orchestrator — 主编排器（Flash，默认入口）
• solo — 单模型内联执行器（Pro，主 Agent）
• planner — 规划与方案设计（Flash）
• deep-worker — 重型实现（Pro）
• oracle — 根因分析与深度理解（Pro，只读）
• reviewer — 代码审查（Pro，只读）
• ui-builder — 前端 / UI 开发（Flash）
• consultant — 方案讨论与建议（Flash）
• explore — 代码库探索（Flash，只读）
• librarian — 文档检索（Flash，只读）
• light-orchestrator — 轻量任务执行（Flash）
• vision — 多模态识别（Flash-Vision，只读）

2.6.3 验证 Orchestrator 路由

输入一个自然语言请求，观察 Orchestrator 是否自动分析意图并路由到合适的 Agent：

「帮我看看这个项目的结构」

Orchestrator 应自动识别为探索类请求，调度 explore Agent（携带 codemap 技能）执行。

「这段代码有个性能问题，帮我排查一下」

Orchestrator 应调度 oracle Agent 进行分析，若需要修复则再调度 deep-worker。

2.6.4 验证命令别名

输入 /help 查看已加载的自定义命令。本配置仓库提供了 17 条命令别名，分为 Agent 路由命令、操作命令、内联命令和规约命令四类：

2.6.5 验证技能加载

OpenCode 的技能（Skills）按需加载。技能按需加载，可通过 /codemap 等命令触发演示，或直接查看 skills/ 目录下的 SKILL.md 文件。

2.7 常见安装问题排查

2.7.1 OpenCode 版本过旧

症状：启动后找不到 DeepSeek provider，或 /connect 列表中无 DeepSeek 选项。

解决：

opencode --version
# 如果版本低于 v1.18.x，请升级

升级方式取决于你的安装方式：

# 一键安装脚本（直接覆盖）
curl -fsSL https://opencode.ai/install | bash

# Homebrew
brew upgrade opencode

# npm
npm update -g opencode-ai

# Scoop
scoop update opencode

2.7.2 API Key 格式错误或未充值

症状：发送消息后返回 401 Unauthorized 或 402 Payment Required。

解决：

• 检查 API Key 是否完整复制（以 sk- 开头）
• 确认 API Key 未被意外撤销（登录 DeepSeek 控制台查看）
• 确认账户余额充足（控制台 → 充值页面查看余额）
• 如果 Key 已泄露，立即删除并创建新 Key

2.7.3 配置目录未被识别

症状：启动 OpenCode 后未加载自定义 Agent 或命令别名。

解决：

• 确认 OPENCODE_CONFIG_DIR 环境变量已正确设置并指向仓库内的 opencode/ 子目录（而非仓库根目录）
• 如果使用符号链接方式，确认 ~/.config/opencode 链接已正确指向 .../my-opencode-deepseek-config/opencode
• 检查目录结构：应直接包含 agents/、skills/ 等子目录（而非套了一层仓库名目录）
• 验证环境变量是否生效（Windows 需重启终端或启动新会话，Linux/macOS 需重新 source）

# 检查配置目录结构（符号链接方式）
ls ~/.config/opencode/
# 或（环境变量方式）
ls $OPENCODE_CONFIG_DIR
# 应看到：agents/  skills/  AGENTS.md  opencode.jsonc  dcp.jsonc  ...

2.7.4 网络代理配置

症状：在中国大陆使用时，可能遇到 GitHub 克隆缓慢或 DeepSeek API 连接超时。

解决：

GitHub 克隆加速：

# 使用代理（如果有）
git clone https://github.com/znlgis/my-opencode-deepseek-config.git
# 或配置 Git 代理
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# 或使用国内镜像（如 ghproxy）
git clone https://ghproxy.com/https://github.com/znlgis/my-opencode-deepseek-config.git

OpenCode 代理配置：

OpenCode 本身通过 DeepSeek API 通信，不走本地代理设置。如有需要，可以在系统层面配置 HTTPS 代理：

# Windows PowerShell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
opencode

# Linux / macOS
export HTTPS_PROXY="http://127.0.0.1:7890"
opencode

2.7.5 权限问题

症状：Linux/macOS 下执行 opencode 报 Permission denied。

解决：

# 确认文件有执行权限
chmod +x ~/.opencode/bin/opencode

# 或将安装目录加入 PATH
export PATH="$HOME/.opencode/bin:$PATH"

2.7.6 OpenCode TUI 显示异常

症状：TUI 界面渲染不正常，出现乱码或闪烁。

解决：

• Windows 用户：使用 Windows Terminal 而非 CMD 或旧版 PowerShell
• macOS 用户：推荐 iTerm2 或 Kitty
• Linux 用户：确认终端支持 256 色和 Unicode
• 尝试将终端字体设置为支持 Nerd Font 的字体（如 FiraCode Nerd Font）

2.8 升级与更新

2.8.1 更新 OpenCode 本身

根据你的安装方式选择对应的升级命令：

# 一键安装脚本（重新执行即覆盖安装）
curl -fsSL https://opencode.ai/install | bash

# Homebrew
brew upgrade opencode

# npm
npm update -g opencode-ai

# Scoop
scoop update opencode

# Arch Linux
sudo pacman -Syu opencode

建议定期检查更新，OpenCode 迭代速度很快，新版本可能带来更好的 DeepSeek 支持和新功能。

2.8.2 更新配置仓库

本配置仓库会持续迭代优化。要获取最新的配置更新，进入仓库根目录（而非 opencode/ 子目录）执行拉取：

# 进入仓库根目录
cd /path/to/my-opencode-deepseek-config    # 或你的实际克隆路径

# 拉取最新代码
git pull origin main

重要：git pull 前请确认你没有在本地修改过配置文件。如果你对配置文件做了自定义修改，建议先 git stash 保存本地更改，拉取后再 git stash pop 合并，或手动解决冲突。

2.8.3 配置文件备份建议

在进行任何升级操作前，建议备份当前配置：

# 备份整个配置目录
cp -r /path/to/my-opencode-deepseek-config /path/to/my-opencode-deepseek-config.backup.$(date +%Y%m%d)

# 或仅备份关键文件
mkdir -p ~/opencode-backup
cp /path/to/my-opencode-deepseek-config/opencode/opencode.jsonc ~/opencode-backup/
cp /path/to/my-opencode-deepseek-config/opencode/AGENTS.md ~/opencode-backup/

如果你的配置做了较多自定义修改，也可以考虑 Fork 本仓库，将自己的修改提交到 Fork 后的仓库中，通过 Git 来管理配置的版本和同步。这是推荐的长期维护方式。

2.8.4 回滚到旧版本

如果升级后遇到兼容性问题，可以通过 Git 回滚配置：

cd /path/to/my-opencode-deepseek-config    # 进入仓库根目录
git log --oneline -10                      # 查看最近的提交记录
git checkout <commit-hash>                 # 回滚到指定提交

对于 OpenCode 本身回滚，请参考各包管理器的降级命令，例如：

# Homebrew
brew install anomalyco/tap/opencode@1.18.0

2.9 部署后检查清单

在完成全部安装步骤后，请对照以下清单逐项确认：

• OpenCode 版本 >= v1.18.x（opencode --version）
• DeepSeek API Key 已获取并充值
• /connect 已成功连接 DeepSeek provider
• /models 显示 deepseek/deepseek-v4-pro 为主模型
• 配置仓库已克隆到正确位置
• Agent 列表包含 12 个 Agent
• /help 显示 18 条自定义命令
• Orchestrator 能正确路由请求
• 已完成配置文件备份

全部通过后，恭喜 —— 你的 OpenCode × DeepSeek 多 Agent 协作环境已就绪！现在可以进入 第三章：模型配置详解，深入了解三模型分工与路由策略。

下一章：第三章：模型配置详解 —— 深入讲解 DeepSeek V4 Pro、Flash 与 Flash-Vision-Exp 的模型分工原则、Provider 配置细节、thinking mode 启用方式以及 Subagent 的模型分配逻辑。