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

本章从零开始，一步一步带你完成 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），需要有效的 API Key。详见 2.2 节。

3. OpenCode >= v1.14.24

DeepSeek provider 从 v1.14.24 起被 OpenCode 内置支持，无需安装任何额外插件。如果之前安装过旧版本，建议先卸载再重新安装。

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 Pro 模型定价极低：输入约 ¥1/百万 tokens，输出约 ¥4/百万 tokens
• DeepSeek V4 Flash 模型价格更低，适合轻量任务

提示：首次使用建议充值 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 中已预设 DeepSeek 为唯一 Provider，并做了模型隔离：

{
  "model": "deepseek/deepseek-v4-pro",
  "small_model": "deepseek/deepseek-v4-flash",
  "enabled_providers": ["deepseek"],
  "disabled_providers": ["openai", "anthropic", "google", "openrouter"]
}

如需启用 DeepSeek V4 Pro 的 thinking/reasoning 能力，可在配置中追加：

"provider": {
  "deepseek": {
    "models": {
      "deepseek-v4-pro": {
        "options": {
          "thinking": { "type": "enabled" }
        }
      }
    }
  }
}

模型 ID 命名规则：OpenCode 中模型的完整标识为 provider_id/model_id，即 deepseek/deepseek-v4-pro 和 deepseek/deepseek-v4-flash。

2.5 克隆配置仓库

本配置仓库包含 10 个 Agent 定义、18 个技能文件、全局规则（AGENTS.md）、插件配置（dcp.jsonc）和主配置文件（opencode.jsonc）。推荐直接克隆到 OpenCode 的标准全局配置目录，实现零额外配置即可生效。

2.5.1 方式一：克隆到全局配置目录（推荐）

~/.config/opencode 是 OpenCode 的标准全局配置路径。将仓库克隆到此目录后，agents/、skills/、AGENTS.md 等文件会被 OpenCode 自动识别和加载。

Windows（PowerShell）：

# 创建 .config 目录（如果尚不存在）
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config"

# 克隆仓库到标准路径
git clone https://github.com/znlgis/my-opencode-deepseek-config.git "$env:USERPROFILE\.config\opencode"

Linux / macOS：

# 克隆仓库到标准路径
git clone https://github.com/znlgis/my-opencode-deepseek-config.git ~/.config/opencode

兼容性说明：该仓库的文件布局严格遵循 OpenCode 的约定 —— agents/ 目录存放 Agent 系统提示、skills/ 目录存放可复用技能、AGENTS.md 作为全局规则文件。克隆到标准路径后，无需任何额外配置即可被自动识别。如果克隆到了其他路径，可通过 OPENCODE_CONFIG_DIR 环境变量指定，见下一节。

克隆完成后，目录结构如下：

~/.config/opencode/
├── agents/                     ← 10 个 Agent 系统提示
│   ├── orchestrator.md         ← 主编排器
│   ├── planner.md
│   ├── deep-worker.md
│   ├── oracle.md
│   ├── reviewer.md
│   ├── consultant.md
│   ├── ui-builder.md
│   ├── explore.md
│   ├── librarian.md
│   └── light-orchestrator.md
├── skills/                     ← 18 个可复用技能
│   ├── gh-cli/SKILL.md
│   ├── code-review/SKILL.md
│   ├── spec-workflow/SKILL.md
│   └── ...（共 18 个）
├── AGENTS.md                   ← 全局规则（所有 Agent 共享）
├── opencode.jsonc              ← 主配置文件
├── dcp.jsonc                   ← DCP 智能压缩插件配置
├── LICENSE
└── README.md

2.5.2 方式二：克隆到任意位置 + 环境变量

如果你不希望将配置放在 ~/.config 下，可以克隆到任意目录并通过环境变量指定：

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

# Linux / macOS
git clone https://github.com/znlgis/my-opencode-deepseek-config.git /path/to/opencode-config
export OPENCODE_CONFIG_DIR="/path/to/opencode-config"
opencode

提示：如果配置目录中缺少某些文件（如 opencode.jsonc 或 AGENTS.md），OpenCode 会使用内置默认值。建议保持仓库文件完整以获得最佳体验。

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"
  

• 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 加载

本配置仓库定义了 10 个 Agent。检查 Agent 列表确认所有 Agent 已被识别：

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

2.6.3 验证 Orchestrator 路由

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

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

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

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

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

2.6.4 验证命令别名

输入 /help 查看已加载的自定义命令。本配置仓库提供了 23 个命令别名，包括：

2.6.5 验证技能加载

OpenCode 的技能（Skills）按需加载。你可以通过 /skill 命令查看已安装的技能列表，或者直接使用命令别名触发对应的技能。例如输入 /codemap，系统应自动加载 codemap 技能并生成当前仓库的结构图。

2.7 常见安装问题排查

2.7.1 OpenCode 版本过旧

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

解决：

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

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

# 一键安装脚本（直接覆盖）
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 或命令别名。

解决：

• 确认仓库已正确克隆到 ~/.config/opencode 目录
• 如果使用自定义路径，确认 OPENCODE_CONFIG_DIR 环境变量已正确设置并指向仓库根目录
• 检查目录结构：应直接包含 agents/、skills/ 等子目录（而非套了一层仓库名目录）
• 验证环境变量是否生效（Windows 需重启终端，Linux/macOS 需重新 source）

# 检查配置目录结构
ls ~/.config/opencode/
# 应看到：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 ~/.config/opencode
# 或配置 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 ~/.config/opencode

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 更新配置仓库

本配置仓库会持续迭代优化。要获取最新的配置更新：

# 进入配置目录
cd ~/.config/opencode    # 或你的自定义路径

# 拉取最新代码
git pull origin main

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

2.8.3 配置文件备份建议

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

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

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

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

2.8.4 回滚到旧版本

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

cd ~/.config/opencode
git log --oneline -10       # 查看最近的提交记录
git checkout <commit-hash>  # 回滚到指定提交

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

# Homebrew
brew install anomalyco/tap/opencode@1.14.24

2.9 部署后检查清单

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

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

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

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