部署 OpenCode 指南 | 个人技术学习

这篇内容是记录部署 OpenCode 的指南，整理了最顺滑的安装路径，踩过的坑都帮你填平了，直接跟着走就行。
面向公网环境，使用国内公网镜像源加速。

步骤概览

步骤	安装内容	作用
1	Python + pip + uv	Python 包管理和运行环境，uv 是极速包管理器，很多 MCP 服务器用它启动（`uvx`）
2	Node.js + npm + npx + bun	JavaScript 运行时，部分 MCP 服务器用它启动（`npx -y`），npm 是全球最大生态
3	rg (ripgrep)	高性能正则搜索工具，OpenCode 代码搜索依赖它
4	OpenCode	AI 编程助手本体，装完就能用
5	配置 OpenCode	配置模型、Provider、MCP 扩展等
6	增强工具（可选）	OpenSpec 工作流、CodeGraph 代码分析、Skills、MCP 扩展

为什么要装 Python 和 Node.js 两个运行时？
因为不同的 MCP 服务器依赖不同——有的用 uvx（Python），有的用 npx -y（Node.js），有的用 bunx（Bun）。装全了才能跑所有 MCP。

1. 安装 Python

Windows

前往 python.org/downloads/ 下载最新版（推荐 3.14.x）。

安装时勾选：

✅ Add Python to PATH
✅ Install pip

完成后验证：

python --version
pip --version

Linux

sudo apt install python3 python3-pip
python3 --version
pip3 --version

配置 pip 镜像源（避免网络问题）

Windows：

pip config set --global global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
pip config set --global global.trusted-host pypi.tuna.tsinghua.edu.cn

Linux：

pip config set --global global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
pip config set --global global.trusted-host pypi.tuna.tsinghua.edu.cn

安装 uv（现代 Python 包管理器）

uv 是 Rust 写的，极速。很多 MCP 服务器用 uvx 启动，所以这个必须装。

Windows：

pip install uv

Linux：

pip install uv --break-system-packages

装完后设置镜像源环境变量（重要）：

Windows：

setx UV_DEFAULT_INDEX "https://pypi.tuna.tsinghua.edu.cn/simple/"

Linux：

echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple/"' >> ~/.bashrc
source ~/.bashrc

Windows 额外步骤 — 把 pip 安装的工具集路径加入 PATH：

# Python 314 是示例版本号，按你实际装的版本来
setx PATH "%PATH%;%APPDATA%\Python\Python314\Scripts"

验证（刚加完环境变量的话，建议新起一个终端验证）：

uv --version

2. 安装 Node.js

Windows

前往 nodejs.org，下载 Windows Installer (.exe)，装完自带 npm。

完成后验证：

node --version
npm --version

Linux

sudo apt install npm
node --version
npm --version

配置 npm 镜像源（必做！）

npm config -g set registry https://registry.npmmirror.com/

安装 npx 和 bun

Windows：

npm install -g npm npx bun --force --verbose
npx --version
bun --version

Linux：

sudo npm install -g npm npx bun --force --verbose
npx --version
bun --version

Windows 额外步骤 — 把 npm 安装的工具集路径加入 PATH：

setx PATH "%PATH%;%APPDATA%\npm"

验证（刚加完环境变量的话，建议新起一个终端验证）：

npm config get registry
# 输出: https://registry.npmmirror.com/

3. 安装 ripgrep (rg)

OpenCode 的代码搜索依赖 rg（ripgrep），高性能正则搜索工具。

Windows

前往 GitHub BurntSushi/ripgrep/releases 下载对应版本的 .zip，解压后将 rg.exe 所在目录加入 PATH。

Linux

sudo apt install ripgrep

验证：

rg --version

4. 安装 Windows Terminal（仅 Windows 用户）

Windows 11 已经自带了，Windows 10 需要手动装。

OpenCode 的 TUI 界面在旧版 cmd/PowerShell 里渲染极差，必须用现代终端。

Win11 用户

直接用自带的 Windows Terminal，不需要额外操作。

Win10 用户

去 GitHub microsoft/terminal/releases 下载安装包，文件名类似：

Microsoft.WindowsTerminal_1.24.11321.0_8wekyb3d8bbwe.msixbundle_Windows10_PreinstallKit.zip

下载后解压，按顺序安装：

# 先装依赖
Add-AppxPackage Microsoft.UI.Xaml.2.8_8.2501.31001.0_x64__8wekyb3d8bbwe.appx

# 再装 Terminal
Add-AppxPackage c2f7b75d3a254ecfba18ef1b738195ab.msixbundle

装完后建议设为默认终端：设置 → 启动 → 默认终端应用程序 → 选「Windows 终端」。

推荐字体：Cascadia Code（自带）或 JetBrains Mono。

使用 PowerShell 作为基础终端

建议默认使用 PowerShell 作为终端环境，体验最好。

打开 Windows Terminal → 设置 → 启动 → 默认配置文件 → 选「PowerShell」。

5. 安装 OpenCode

Windows：

npm install -g opencode-ai

Linux：

sudo npm install -g opencode-ai --verbose

验证（刚加完环境变量的话，建议新起一个终端验证）：

opencode --version

6. 配置 OpenCode

配置文件在 ~/.config/opencode/opencode.jsonc（Windows 上对应 C:\Users\<用户名>\.config\opencode\opencode.jsonc）。

完整配置示例（含 model + mcp）放在下一节，增强工具安装完成后查看。

7. 增强工具（OpenSpec / CodeGraph / Skills / MCP）

这些是 OpenCode 的能力扩展，按需安装。

7.1 OpenSpec — 结构化变更工作流

GitHub: anomalyco/openspec

OpenSpec 提供从「想法」到「实现」的完整流程，是 OpenCode 内置的工作流引擎。

安装：

Windows：

npm install -g @fission-ai/openspec

Linux：

sudo npm install -g @fission-ai/openspec --verbose

验证：

openspec --version

Shell 补全：

openspec completion install

初始化（每个项目只需做一次）：

cd your-project
openspec init --tools opencode

openspec init 会在项目中创建 .openspec.yaml 配置文件和 .opencode/ 目录（包含 skills、commands 等）。建议将 .openspec.yaml 加入 Git。

配置编辑：

openspec config edit

重置 Profile：

openspec profile reset --all -y

初始化完成后，OpenCode 会自动发现并加载对应的 Skills（openspec-explore、openspec-propose 等）。

参考文档：

五个核心命令：

命令	功能
`/opsx-explore`	探索模式，脑暴和分析，充当思考伙伴
`/opsx-propose`	创建提案，生成 proposal/design/tasks 三件套
`/opsx-apply`	按任务清单逐步实施开发
`/opsx-sync`	将 delta spec 同步到主 spec
`/opsx-archive`	归档完成的变更

工作流示意：

graph TD
    A[需求/想法] --> B[/opsx-explore 探索模式]
    B --> C{是否形成方案?}
    C -->|是| D[/opsx-propose 创建提案]
    C -->|否| B
    D --> E[proposal.md 提案]
    D --> F[design.md 设计]
    D --> G[tasks.md 任务]
    G --> H[/opsx-apply 实施]
    H --> I[逐任务开发]
    I --> J{全部完成?}
    J -->|是| K[/opsx-archive 归档]
    J -->|发现问题| L[更新设计]
    L --> H

7.2 CodeGraph — 代码关系图谱

GitHub: anomalyco/codegraph

CodeGraph 是 OpenCode 的代码智能分析引擎，由 Anomalyco（OpenCode 同团队）开发。它能够理解代码间的调用关系、依赖和影响范围，让 AI 真正读懂代码，而不仅仅是做文本匹配。

安装：

Windows：

npm install -g @colbymchenry/codegraph

Linux：

sudo npm install -g @colbymchenry/codegraph --verbose

验证：

codegraph --version

接入 OpenCode（全局，一次性）：

codegraph install -t opencode -l global -y

初始化项目（每个项目只需做一次）：

cd your-project
codegraph init

codegraph init 会在项目中创建 .codegraph/ 目录并建立初始索引。建议将 .codegraph/ 加入 .gitignore。

初始化完成后，OpenCode 内置的所有 codegraph 工具（codegraph_explore、codegraph_search 等）即可直接在对话中使用。

核心工具：

工具	功能
`codegraph_explore`	自然语言查询代码，理解架构和流程
`codegraph_search`	按名称搜索符号（函数、类、接口等）
`codegraph_node`	查看单个符号的详细信息、调用链
`codegraph_callers`	查看谁调用了某个函数
`codegraph_callees`	查看某个函数调用了谁
`codegraph_impact`	分析修改某个符号会影响到哪些文件
`codegraph_files`	索引化的项目文件树
`codegraph_status`	索引健康检查

7.3 Skills — 技能扩展

Skills 是 OpenCode 的可插拔技能模块，按需安装。

npx skills add https://github.com/vercel-labs/skills --skill find-skills
npx skills add vercel-labs/agent-skills --skill skill-creator

7.4 MCP — 模型上下文协议扩展

官网: modelcontextprotocol.io
官方服务器: github.com/modelcontextprotocol/servers（86.9k ⭐）

MCP（Model Context Protocol）是 Anthropic 主导的 AI 外接工具标准，像 USB-C 一样为 AI 应用提供连接外部系统的标准化方式。OpenCode 支持 MCP，只需在配置中声明即可让 AI 调用外部工具。

强烈推荐安装的 MCP：

MCP	项目地址	功能	启动方式
codegraph	anomalyco/codegraph	代码索引和分析，让 AI 真正理解代码结构和调用关系。OpenCode 的代码分析能力就靠它	已通过 `codegraph install` 接入
context7	upstash/context7	搜索开源库的最新文档（包含版本特定信息），避免 AI 生成过时或 hallucinated 的 API	https://mcp.context7.com/mcp
fetch	modelcontextprotocol/servers - fetch	抓取网页内容并转换为 markdown，方便 AI 读取网页信息。支持分块读取长页面	`uvx mcp-server-fetch`
gh-grep	k1LoW/gh-grep	在 GitHub 百万级公开仓库中搜索真实代码模式（不是关键词搜索），找实际使用案例。比 GitHub 搜索更精准，适合找真实代码示例	https://mcp.grep.app
sequential-thinking	modelcontextprotocol/servers - sequentialthinking	链式思考工具，增强复杂问题的推理能力。将问题分解为一步步思考，支持分支和修订	`npx -y @modelcontextprotocol/server-sequential-thinking`
playwright	@playwright/mcp	浏览器自动化，可以做 UI 测试、网页截图、数据抓取等。支持 Chromium/Firefox/WebKit	`npx -y @playwright/mcp`
markitdown	nicck/markitdown	将 PDF、Word、PPT、EPUB 等文档转换为 markdown，方便 AI 读取文档内容	`uvx markitdown-mcp`

context7 和 gh-grep 不申请 Key 也能用，申请后调用配额会更多。
建议把全局 MCP 写在 ~/.config/opencode/opencode.jsonc，项目级 MCP 写在 <project>/.opencode/opencode.jsonc。

8. OpenCode 完整配置示例

将以下内容写入 ~/.config/opencode/opencode.jsonc，包含 model、provider、mcp 三部分配置：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "~/.config/opencode/AGENTS.md"
  ],
  "compaction": {
    "auto": true,
    "strategy": "summarize",
    "threshold": 0.95,
    "prune_tool_outputs": true
  },
  "model": "zhipu/glm-5.1",
  "provider": {
    "zhipu": {
      "name": "zhipu",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://open.bigmodel.cn/api/paas/v4",
        "apiKey": "xxx.xxx"
      },
      "models": {
        "glm-5.1": {},
        "glm-4.7": {},
        "glm-4-air": {}
      }
    },
    "authropic": {
      "name": "authropic",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "apiKey": "sk-ant-xxx"
      },
      "models": {
        "claude-sonnet-4": {},
        "claude-3.7-sonnet": {},
        "claude-3.5-haiku": {}
      }
    }
  },
  "mcp": {
    "gh-grep": {
      "type": "remote",
      "url": "https://mcp.grep.app",
      "enabled": true
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": ""
      },
      "enabled": true
    },
    "fetch": {
      "type": "local",
      "command": ["uvx", "mcp-server-fetch"],
      "enabled": true
    },
    "sequential-thinking": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-sequential-thinking"],
      "enabled": true
    },
    "codegraph": {
      "type": "local",
      "command": ["codegraph", "serve", "--mcp"],
      "enabled": false
    },
    "markitdown": {
      "type": "local",
      "command": ["uvx", "markitdown-mcp"],
      "enabled": false
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": false
    }
  }
}

按你的实际 API Key 修改上面的 apiKey 字段。默认使用智谱（zhipu）作为主 Provider，也可按需切换为 Anthropic、OpenRouter 或其他兼容 OpenAI API 的服务。

9. 镜像源配置速查

pip

pip config set --global global.index-url https://pypi.tuna.tsinghua.edu.cn/simple/
pip config set --global global.trusted-host pypi.tuna.tsinghua.edu.cn

uv

Windows：

setx UV_DEFAULT_INDEX "https://pypi.tuna.tsinghua.edu.cn/simple/"

Linux：

echo 'export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple/"' >> ~/.bashrc

npm

npm config -g set registry https://registry.npmmirror.com/

10. PATH 环境变量速查（仅 Windows）

# uv（按实际 Python 版本号）
%APPDATA%\Python\Python314\Scripts

# npm 全局
%APPDATA%\npm

11. 问题记录

Windows

VSCode + Remote SSH 按下 CAPS LOCK 会输出白字符：已知问题，暂无完美解决方案，建议避免在 Remote SSH 会话中使用 CAPS LOCK。
1.16.2 问题已经消失。

Linux

复制失效（Ctrl + Insert / 鼠标选中等）：按住 Shift 之后使用鼠标选择即可正常复制。
Ctrl + Enter 不能换行：改用 Alt + Enter 或 Ctrl + J。

MCP npx error fix

如果 MCP 启动时遇到 npx 相关错误：

sudo npm install -g npm --force
npm cache clean --force

总结

按这个顺序走完：

✅ 装 Python + pip 镜像 + uv + 环境变量
✅ 装 Node.js + npm 镜像 + bun + npx + 环境变量
✅ 装 ripgrep (rg)
✅ 装 Windows Terminal（仅 Win10 手动装，Win11 自带）
✅ npm install -g opencode-ai
✅ 装 OpenSpec + CodeGraph + Skills + MCP 扩展（增强工具）
✅ 初始化项目（openspec init / codegraph init）
✅ 配置 opencode.jsonc（参考第 8 节完整示例）

全程使用国内公网镜像源加速，无需内网环境。