技术知识库

Appearance

aiopencodetoolohmyopenagent

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 文件夹（用于存放全局模块和缓存）：

创建 Node 全局 npm 文件夹

1.2 配置环境变量 ​

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

用户变量（Path 中添加）： 用户变量 Path 配置

系统变量（新建 NODE_PATH）： 系统变量 NODE_PATH 配置

2 安装 OpenCode ​

2.1 什么是 OpenCode ​

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

2.2 Windows 安装 ​

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

bash
npm install -g opencode-ai

验证安装：

bash
opencode --version

其他安装方式：

bash
# Chocolatey
choco install opencode

# Scoop
scoop install opencode

2.3 macOS / Linux 安装 ​

bash
# 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 并初始化：

bash
cd /path/to/your-project
opencode

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

bash
/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：

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. 点击设置 → 开启路由功能：

ccswitch 开启路由功能

  1. 点击右上角 + 号新建模型配置，填入公司 API 信息：
  • 模型端点 和 API Key：在 统一门户 → AI Hub → 能力中心 → 统一大模型网关 获取

模型端点与 API Key 配置

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

获取可用模型列表

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

两种方式对比

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

3.4 设置环境变量 ​

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

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

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

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

3.5 选择模型 ​

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

bash
/models

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

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

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

bash
/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 ​

bash
# 克隆仓库
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 管理配置 ​

bash
# 查看当前配置
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 对话中直接输入：

bash
/skill install <skill-name>

例如安装安全审查 Skill：

bash
/skill install security-review

方式二：从 GitHub 仓库安装 ​

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

方式三：手动安装 ​

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

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

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

5.3 自定义 Skill 示例 ​

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

markdown
# 公司代码审查助手

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

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

5.4 常用 Skill 推荐 ​

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

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

6 MCP 配置 ​

6.1 什么是 MCP ​

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

6.2 在 opencode.json 中配置 MCP ​

json
{
  "$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 对话中运行：

bash
/mcp

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

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

7 Hooks 与 Plugin 扩展 ​

7.1 什么是 Hooks ​

OpenCode 通过 Plugin 系统 实现 Hook 机制。Plugin 是 JavaScript/TypeScript 模块，可以订阅 OpenCode 生命周期中的各种事件，在特定时间点执行自定义逻辑。

与 Claude Code 的声明式 Hook 配置不同，OpenCode 的 Hook 是编程式的，通过插件导出的函数来实现。

7.2 插件配置方式 ​

方式一：通过 npm 包安装

在 opencode.json 中配置：

json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session",
    "opencode-wakatime",
    "@my-org/custom-plugin"
  ]
}

方式二：本地插件

将插件文件放在以下目录：

bash
# 项目级
.opencode/plugins/my-plugin.ts

# 全局
~/.config/opencode/plugins/my-plugin.ts

7.3 所有可用事件 ​

事件类别事件名触发时机
工具事件tool.execute.before工具执行之前
tool.execute.after工具执行之后
命令事件command.executed命令执行完成
文件事件file.edited文件被编辑
file.watcher.updated文件监听器检测到变更
安装事件installation.updated安装更新时
LSP 事件lsp.client.diagnosticsLSP 诊断更新
lsp.updatedLSP 状态变更
消息事件message.part.removed消息部分被移除
message.part.updated消息部分被更新
message.removed消息被移除
message.updated消息被更新
权限事件permission.asked请求权限时
permission.replied权限被响应时
服务器事件server.connected服务器连接成功
会话事件session.created会话创建
session.compacted会话压缩（上下文窗口管理）
session.deleted会话删除
session.diff会话差异
session.error会话错误
session.idle会话空闲
session.status会话状态变更
session.updated会话更新
TODO 事件todo.updatedTODO 列表更新
Shell 事件shell.envShell 环境变更
TUI 事件tui.prompt.append提示内容追加
tui.command.executeTUI 命令执行
tui.toast.showToast 通知显示

7.4 插件开发示例 ​

基础插件结构 ​

typescript
// .opencode/plugins/my-plugin.ts
import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async (ctx) => {
  return {
    // 在这里实现 Hook
  }
}

保护 .env 文件 ​

防止 OpenCode 读取 .env 文件中的敏感信息：

typescript
// .opencode/plugins/env-protection.ts
export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "read" && output.args.filePath.includes(".env")) {
        throw new Error("Do not read .env files")
      }
    },
  }
}

Bash 命令安全转义 ​

自动对 Bash 命令进行安全转义：

typescript
// .opencode/plugins/shell-escape.ts
import { escape } from "shescape"

export const ShellEscape = async (ctx) => {
  return {
    "tool.execute.before": async (input, output) => {
      if (input.tool === "bash") {
        output.args.command = escape(output.args.command)
      }
    }
  }
}

会话压缩时注入上下文 ​

在上下文窗口压缩时保留重要状态：

typescript
// .opencode/plugins/compaction-context.ts
import type { Plugin } from "@opencode-ai/plugin"

export const CompactionPlugin: Plugin = async (ctx) => {
  return {
    "experimental.session.compacting": async (input, output) => {
      output.context.push(`
## Custom Context

Include any state that should persist across compaction:
- Current task status
- Important decisions made
- Files being actively worked on
`)
    },
  }
}

7.5 Claude Code Hooks vs OpenCode Hooks 对比 ​

维度Claude Code HooksOpenCode Hooks
配置方式声明式 JSON 配置编程式 TypeScript 插件
事件数量20+ 事件20+ 事件
实现方式Shell 命令 / HTTP / PromptJS/TS 函数
配置文件~/.claude/settings.jsonopencode.json 中 plugin 数组
本地插件通过 Shell 脚本.opencode/plugins/ 目录
灵活性低（声明式）高（编程式，可访问完整 API）
学习曲线低中（需要 TypeScript）

8 OpenCode vs Claude Code 对比 ​

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

8 快速上手指南 ​

新员工 5 分钟上手流程 ​

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

bash
# 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 手动配置）：

bash
# 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，开始编码

参考资源 ​

数字化发展中心 · IT共享服务中心

Copyright © 2026