OpenCode 使用指南

本教程将指导您完成 OpenCode 的安装、公司 API 适配、Skill 安装以及 MCP 配置，帮助新员工快速搭建 AI 编程助手环境。同时推荐 Oh My OpenAgent 框架，进一步简化配置流程。

1 npm 环境配置

OpenCode 基于 Node.js 运行，需要先配置 npm 环境。

1.1 安装 Node.js

访问 Node.js 官网 下载并安装 LTS 版本，安装路径建议修改为 D:\Program Files\nodejs。

安装完成后，在 Node.js 安装目录下创建全局 npm 文件夹（用于存放全局模块和缓存）：

1.2 配置环境变量

在系统环境变量中分别配置用户变量和系统变量：

用户变量（Path 中添加）：

系统变量（新建 NODE_PATH）：

2 安装 OpenCode

2.1 什么是 OpenCode

OpenCode 是一款开源的 AI 编程助手，支持终端（TUI）、桌面应用和 IDE 插件三种使用方式。相比 Claude Code，OpenCode 的最大优势是原生支持任意 OpenAI 兼容的 API 端点，非常适合接入公司内部模型网关。

2.2 Windows 安装

推荐使用 npm 全局安装（Windows 环境首选）：

npm install -g opencode-ai

验证安装：

opencode --version

其他安装方式：

# Chocolatey
choco install opencode

# Scoop
scoop install opencode

2.3 macOS / Linux 安装

# macOS（Homebrew）
brew install anomalyco/tap/opencode

# Linux / macOS（一键安装脚本）
curl -fsSL https://opencode.ai/install | bash

# 通用 npm 安装
npm install -g opencode-ai

2.4 初始化项目

进入项目目录，启动 OpenCode 并初始化：

cd /path/to/your-project
opencode

在 OpenCode 对话中运行初始化命令：

/init

OpenCode 会自动分析项目结构，生成 AGENTS.md 文件，帮助 AI 理解项目上下文。

3 配置公司 API（自定义 Provider）

OpenCode 提供两种方式接入公司 API：手动编辑 opencode.json（灵活、适合进阶用户）和 ccswitch 图形化配置（直观、推荐小白使用）。

3.1 获取 API 凭证

在 统一门户 → AI Hub → 能力中心 → 统一大模型网关 获取以下信息：

• API 端点地址（Base URL），例如 https://api-gateway.company.com/v1
• API Key

3.2 方式一：通过 opencode.json 配置（进阶）

直接在配置文件中声明 Provider，适合熟悉 JSON 配置的用户。

在项目根目录（或全局 ~/.config/opencode/）创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "company": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "公司内部模型",
      "options": {
        "baseURL": "https://api-gateway.company.com/v1",
        "apiKey": "{env:COMPANY_API_KEY}"
      },
      "models": {
        "deepseek-v4": {
          "name": "DeepSeek V4 Pro",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        },
        "qwen3-coder": {
          "name": "Qwen3 Coder 480B",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "company/deepseek-v4",
  "small_model": "company/deepseek-v4"
}

配置说明

字段	说明
npm	使用 @ai-sdk/openai-compatible 适配所有 OpenAI 兼容 API
baseURL	公司 API 网关地址（以 /v1 结尾）
apiKey	使用 {env:变量名} 从环境变量读取，避免硬编码
models	列出可用模型，limit 指定上下文和输出 token 上限
model	默认使用的主模型
small_model	轻量任务（如标题生成）使用的模型

3.3 方式二：通过 ccswitch 配置（图形化，推荐小白使用）

ccswitch 同样支持 OpenCode，通过图形化界面配置模型路由，无需手动编辑 JSON 文件。

安装 ccswitch

访问 ccswitch 官网 下载并安装。

配置 OpenCode 模型

与 Claude Code 配置流程完全一致，ccswitch 会拦截 OpenCode 的 API 请求并路由到公司网关：

1. 点击设置 → 开启路由功能：

2. 点击右上角 + 号新建模型配置，填入公司 API 信息：

• 模型端点 和 API Key：在 统一门户 → AI Hub → 能力中心 → 统一大模型网关 获取

3. 点击 获取模型，ccswitch 会自动从网关拉取可用模型列表，选择后保存：

4. 在 OpenCode 中运行 /models，ccswitch 代理的模型会自动出现在列表中。

两种方式对比

	opencode.json	ccswitch
配置难度	需要理解 JSON 结构	图形化界面，点点点即可
灵活性	高，可精细控制每个模型参数	中，依赖 ccswitch 支持的功能
适用场景	进阶用户、需要版本控制配置文件	新手、快速上手
多工具共享	仅 OpenCode	同一份配置可同时给 Claude Code 和 OpenCode 使用

3.4 设置环境变量

为避免 API Key 泄露，建议通过环境变量注入：

# Windows（PowerShell）
$env:COMPANY_API_KEY = "your-api-key"

# macOS / Linux
export COMPANY_API_KEY="your-api-key"

或者将上述配置写入 ~/.bashrc 或 ~/.zshrc 持久化。

3.5 选择模型

配置完成后，在 OpenCode 中运行：

/models

即可看到自定义 Provider 下的所有模型，选择即可切换。

3.6 使用 /connect 命令（交互式配置）

OpenCode 也支持通过 /connect 命令交互式添加自定义 Provider：

/connect

选择 Other → 输入 Provider ID（如 company）→ 输入 API Key → 然后在 opencode.json 中补充 baseURL 和 models 即可。

4 Oh My OpenAgent 框架（推荐）

4.1 什么是 Oh My OpenAgent

Oh My OpenAgent（简称 omo）是一个专为 OpenCode 和 Claude Code 设计的一站式配置管理框架。它提供了：

• 一键安装脚本：自动完成 OpenCode 环境搭建
• Provider 认证向导：交互式配置 Anthropic、Gemini、Copilot、Z.AI 等主流 Provider
• OpenCode Zen 集成：快速接入 OpenCode 官方验证模型
• 订阅管理：统一管理多个 AI 服务的订阅状态

4.2 安装 Oh My OpenAgent

# 克隆仓库
git clone https://github.com/code-yeongyu/oh-my-openagent.git
cd oh-my-openagent

# 运行安装脚本
./install.sh

提示

安装脚本会引导您完成 OpenCode 环境检测、Provider 选择和 API Key 配置。对于公司内部 API，选择 "Custom Provider" 并填入公司网关地址即可。

4.3 使用 omo 管理配置

# 查看当前配置
omo config show

# 添加新的 Provider
omo provider add

# 切换默认模型
omo model switch

# 检查环境状态
omo doctor

4.4 为什么推荐 omo

场景	手动配置	使用 omo
新员工入职	阅读文档 → 手动编辑 JSON → 配置环境变量 → 排查问题	运行安装脚本 → 按向导操作 → 完成
多 Provider 切换	手动修改 opencode.json 中的 model 字段	omo model switch 一键切换
环境迁移	复制配置文件 → 手动调整路径	导出配置 → 新环境导入

对于新员工来说，omo 将 OpenCode 的配置门槛从"阅读文档 + 手动配置"降低到"运行脚本 + 按提示操作"，大幅缩短上手时间。

5 Skill 安装

5.1 什么是 Skill

Skill 是结构化的 AI 指令集，用于扩展 OpenCode 的能力。每个 Skill 是一个 Markdown 文件（SKILL.md），告诉 AI 在特定场景下如何工作。

OpenCode 支持 Agent Skills 开放标准，与 Claude Code 的 Skill 生态互通。

5.2 安装 Skill 的方式

方式一：通过命令安装（推荐）

在 OpenCode 对话中直接输入：

/skill install <skill-name>

例如安装安全审查 Skill：

/skill install security-review

方式二：从 GitHub 仓库安装

/skill install https://github.com/user/skill-repo

方式三：手动安装

将 Skill 文件放置到 OpenCode 的 Skills 目录：

# Windows
%USERPROFILE%\.config\opencode\skills\

# macOS / Linux
~/.config/opencode/skills/

5.3 自定义 Skill 示例

创建 .opencode/skills/my-skill/SKILL.md：

# 公司代码审查助手

你是一个熟悉公司技术栈的代码审查助手。审查流程：

1. 检查是否遵循公司编码规范（参考 docs/standards/）
2. 识别潜在的安全漏洞和性能问题
3. 检查是否使用了公司内部 API 的正确调用方式
4. 按优先级排序输出改进建议

5.4 常用 Skill 推荐

Skill	用途
security-review	安全漏洞审查
frontend	前端/UI 开发辅助
debugging	调试和问题排查
git-master	Git 操作辅助
writing-plans	开发计划生成

更多 Skill 可在 Agent Skills 官方市场 浏览和下载。

6 MCP 配置

6.1 什么是 MCP

MCP（Model Context Protocol） 是 Anthropic 推出的开放标准协议，OpenCode 原生支持。通过 MCP，AI 可以调用外部工具和服务（如数据库、API、文件系统等）。

6.2 在 opencode.json 中配置 MCP

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "E:\\code\\my-project"
      ]
    },
    "github": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
      }
    }
  }
}

配置说明

• type: "local"：本地启动的 MCP Server
• type: "remote"：远程 MCP Server（通过 URL 连接）
• command：MCP Server 的启动命令
• args：启动参数
• env：环境变量（支持 {env:变量名} 语法）

6.3 常见 MCP Server 推荐

MCP Server	用途	安装命令
Filesystem	文件系统读写操作	npx @modelcontextprotocol/server-filesystem <path>
GitHub	管理 Issues、PR、仓库	npx @modelcontextprotocol/server-github
Postgres	数据库查询	npx @modelcontextprotocol/server-postgres
Brave Search	网络搜索	npx @modelcontextprotocol/server-brave-search
Context7	技术文档查询	npx @modelcontextprotocol/server-context7

6.4 验证 MCP 配置

在 OpenCode 对话中运行：

/mcp

查看已加载的 MCP Server 列表。如果未正常加载，请检查：

• 命令和参数是否正确
• 环境变量是否已正确设置
• MCP Server 的 npm 包是否已安装

7 OpenCode vs Claude Code 对比

维度	OpenCode	Claude Code
开源	✅ 完全开源	❌ 闭源
自定义 API	✅ 原生支持 OpenAI 兼容 API	⚠️ 需要 ccswitch 等工具中转
Provider 生态	50+ 内置 Provider	仅 Anthropic 官方
配置方式	opencode.json 统一配置	多种配置分散在不同位置
多 Agent	✅ 内置 Agent 系统	⚠️ 支持有限
插件系统	✅ 支持 npm 插件	❌ 不支持
推荐场景	需要使用公司内部 API	深度使用 Anthropic 生态

8 快速上手指南

新员工 5 分钟上手流程

小白推荐路径（使用 ccswitch 图形化配置）：

# 1. 安装 Node.js 和 OpenCode（参考第 1-2 节）
npm install -g opencode-ai

# 2. 安装 ccswitch
# 访问 https://www.ccswitch.io/zh/ 下载安装

# 3. 在 ccswitch 中配置公司 API（参考第 3.3 节）
# 图形化界面，填入端点地址和 API Key，点击"获取模型"即可

# 4. 启动 OpenCode
cd /path/to/your-project
opencode

# 5. 初始化项目
# 在 OpenCode 中输入 /init

# 6. 开始编码！

进阶路径（使用 opencode.json 手动配置）：

# 1. 安装 OpenCode
npm install -g opencode-ai

# 2. 克隆 Oh My OpenAgent（可选，推荐）
git clone https://github.com/code-yeongyu/oh-my-openagent.git
cd oh-my-openagent && ./install.sh

# 3. 配置公司 API 密钥
export COMPANY_API_KEY="从统一门户获取的 Key"

# 4. 创建项目配置文件
# 将第 3.2 节的 opencode.json 内容复制到项目根目录

# 5. 启动 OpenCode
cd /path/to/your-project
opencode

# 6. 初始化项目 /init，开始编码

---

参考资源

• OpenCode 官方文档
• OpenCode Provider 配置指南
• Oh My OpenAgent GitHub
• Oh My OpenAgent 文档
• Agent Skills 标准
• MCP 官方文档