【OpenCode部署】OpenCode + 腾讯云 Token Plan 部署教程 (Windows 版)

OpenCode + 腾讯云 Token Plan 部署教程 (Windows 版)

更新日期: 2026-07-03

---

目录

1. 前置条件
2. [安装 OpenCode](#安装 OpenCode)
3. [腾讯云 Token Plan 配置](#腾讯云 Token Plan 配置)
   • 全局部署配置
   • 局部项目配置
4. 常用指令
5. [添加 MCP 服务器](#添加 MCP 服务器)
6. [配置 LSP 服务器](#配置 LSP 服务器)
7. [Agent 使用 Demo](#Agent 使用 Demo)
8. 故障排查

---

1. 前置条件

条件	说明
Node.js	18+ 版本 (下载)
腾讯云账号	已订阅 Token Plan 套餐
API Key	从腾讯云控制台获取

获取 API Key 步骤：

1. 访问 腾讯云大模型服务平台
2. 点击「订阅 Token Plan 套餐」
3. 复制专属 API Key（格式：sk-xxxxxxxx）

---

2. 安装 OpenCode

方式一：npm 安装（推荐）

npm install -g opencode-ai

方式二：Scoop 安装

scoop install opencode

方式三：Chocolatey 安装

choco install opencode

验证安装：

opencode -v

---

3. 腾讯云 Token Plan 配置

3.1 全局部署配置

全局配置影响所有项目，存放在用户目录下。

配置文件路径：

C:\Users\<用户名>\.config\opencode\opencode.json

创建/编辑该文件 ，替换 $your_api_key 为你的腾讯云 API Key：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tencent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "腾讯云 Token Plan",
      "options": {
        "baseURL": "https://api.lkeap.cloud.tencent.com/plan/v3",
        "apiKey": "$your_api_key"
      },
      "models": {
        "tc-code-latest": {
          "name": "Auto (自动优选)",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        },
        "deepseek-v4-pro-202606": {
          "name": "DeepSeek-V4-Pro",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        },
        "deepseek-v4-flash-202605": {
          "name": "DeepSeek-V4-Flash",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        },
        "glm-5": {
          "name": "GLM-5",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        },
        "glm-5.1": {
          "name": "GLM-5.1",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        },
        "minimax-m2.5": {
          "name": "MiniMax-M2.5",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        },
        "kimi-k2.5": {
          "name": "Kimi-K2.5",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        }
      }
    }
  }
}

然后指定默认模型：

{
  "model": "tencent/tc-code-latest"
}

3.2 局部项目配置

在项目根目录创建 opencode.json，仅影响当前项目，会与全局配置合并（局部优先）。

项目目录/
├── opencode.json          ← 局部配置
└── src/

{
  "$schema": "https://opencode.ai/config.json",
  "model": "tencent/deepseek-v4-pro-202606",
  "provider": {
    "tencent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "腾讯云 (本项目的专用Key)",
      "options": {
        "baseURL": "https://api.lkeap.cloud.tencent.com/plan/v3",
        "apiKey": "$your_project_api_key"
      },
      "models": {
        "deepseek-v4-pro-202606": {
          "name": "DeepSeek-V4-Pro",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        }
      }
    }
  },
  "lsp": true
}

开箱即用的完整局部配置示例（含 LSP + MCP + Agent）：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "tencent/deepseek-v4-pro-202606",
  "lsp": true,
  "provider": {
    "tencent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "腾讯云",
      "options": {
        "baseURL": "https://api.lkeap.cloud.tencent.com/plan/v3",
        "apiKey": "$your_api_key"
      },
      "models": {
        "deepseek-v4-pro-202606": {
          "name": "DeepSeek-V4-Pro",
          "modalities": { "input": ["text"], "output": ["text"] },
          "options": { "thinking": { "type": "enabled" } }
        }
      }
    }
  },
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."],
      "enabled": true
    },
    "git": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-git"],
      "enabled": true
    },
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app",
      "enabled": true
    }
  },
  "agent": {
    "code-reviewer": {
      "description": "审查代码质量和安全问题",
      "mode": "subagent",
      "permission": { "edit": "deny" },
      "prompt": "你是代码审查专家。关注安全、性能、可维护性。输出按严重度分类的报告。"
    },
    "test-writer": {
      "description": "编写单元测试",
      "mode": "subagent",
      "permission": { "bash": { "*": "allow" } },
      "prompt": "你是测试工程师。先检查项目已有测试框架，编写符合现有模式的测试。"
    }
  }
}

---

4. 常用指令

启动与基本操作

指令	说明
opencode	启动 TUI 交互界面
opencode -v	查看版本号
opencode "帮我创建..."	CLI 模式直接执行任务

TUI 内命令

命令	功能
/connect	配置 AI Provider 的 API Key
/models	查看/切换可用模型
/init	初始化项目（自动创建 AGENTS.md）
/undo	撤销最近一次操作
/redo	重做被撤销的操作
/share	分享当前会话链接
/help	查看帮助
/theme	切换主题
/keybinds	查看快捷键

快捷键

按键	功能
Tab	切换主 Agent（Build ↔ Plan）
@	@mention 子 Agent 或文件
↑ / ↓	浏览历史消息
Ctrl + N	新建会话
Ctrl + C	中断当前操作
Esc	退出弹窗/菜单

CLI 命令行模式

# 在项目目录执行一次性任务
opencode "修复 src/utils.js 中的所有 ESLint 警告"

# 使用指定模型
opencode --model "tencent/glm-5" "分析数据库性能问题"

# 后台服务器模式（供桌面应用连接）
opencode serve --hostname 0.0.0.0 --port 4096

# Web 界面模式
opencode web

自定义命令

在 .opencode/commands/ 目录创建 markdown 文件：

.opencode/commands/review.md：

---
description: 代码审查当前改动
agent: build
---
审查最近的变更 !`git diff HEAD~1`，按严重度分类列出问题和修复建议。

使用：输入 /review 即可执行。

---

5. 添加 MCP 服务器

MCP (Model Context Protocol) 为 OpenCode 提供外部工具能力。

5.1 推荐 MCP 清单

开发者必备

MCP	功能	类型	成本
Filesystem	文件读写操作	本地	免费
Git	Git 仓库操作	本地	免费
GitHub	GitHub API（Issues/PR/Workflows）	远程	免费
Grep by Vercel	GitHub 代码搜索	远程	免费

数据库

MCP	功能	类型
SQLite	SQLite 查询	本地
PostgreSQL	PostgreSQL 查询	本地

文档与搜索

MCP	功能	类型	成本
Context7	技术文档搜索	远程	免费额度
Brave Search	网页搜索	远程	免费额度

自动化

MCP	功能	类型
Puppeteer	浏览器自动化（截图、爬取）	本地
Fetch	HTTP 请求	本地

5.2 配置示例

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."],
      "enabled": true
    },
    "git": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-git"],
      "enabled": true
    },
    "github": {
      "type": "remote",
      "url": "https://api.github.com/mcp",
      "oauth": {},
      "enabled": true
    },
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app",
      "enabled": true
    },
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    },
    "sqlite": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-sqlite", "database.sqlite"],
      "enabled": true
    },
    "puppeteer": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-puppeteer"],
      "enabled": true
    },
    "fetch": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-fetch"],
      "enabled": true
    },
    "brave-search": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
      "environment": { "BRAVE_API_KEY": "your_brave_api_key" },
      "enabled": true
    }
  }
}

5.3 MCP 管理命令

opencode mcp list          # 列出所有 MCP 及状态
opencode mcp auth github   # 认证 GitHub MCP（OAuth）
opencode mcp logout github # 移除 GitHub MCP 凭据

5.4 按需启用/禁用

{
  "tools": {
    "puppeteer_*": false,
    "fetch_*": false
  }
}

---

6. 配置 LSP 服务器

LSP (Language Server Protocol) 提供代码诊断和智能提示。

6.1 一键启用所有内置 LSP

{
  "lsp": true
}

OpenCode 内置支持 33+ 种语言的 LSP，自动检测项目使用的语言并启动对应服务器：

LSP 服务器	文件扩展名	条件
typescript	.ts, .tsx, .js, .jsx	项目有 typescript 依赖
pyright	.py, .pyi	已安装 pyright
gopls	.go	可用 go 命令
rust	.rs	可用 rust-analyzer
eslint	.ts, .tsx, .js, .jsx	项目有 eslint 依赖
clangd	.c, .cpp, .h, .hpp	C/C++ 项目
dart	.dart	可用 dart 命令
deno	.ts, .tsx, .js, .jsx	检测到 deno.json
bash	.sh, .bash, .zsh	自动安装
yaml-ls	.yaml, .yml	自动安装
terraform	.tf, .tfvars	自动安装
vue	.vue	Vue 项目
svelte	.svelte	Svelte 项目
astro	.astro	Astro 项目
php intelephense	.php	PHP 项目
jdtls	.java	Java SDK 21+
csharp	.cs, .csx	.NET SDK

6.2 选择性禁用

{
  "lsp": {
    "typescript": { "disabled": true },
    "eslint": { "disabled": true }
  }
}

6.3 自定义 LSP（如非内置语言）

{
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"],
      "env": { "LOG_LEVEL": "debug" },
      "initialization": {
        "preferences": { "autoImport": true }
      }
    }
  }
}

6.4 安装常用 LSP 工具（手动）

# TypeScript/JavaScript
npm install -g typescript typescript-language-server

# Python
pip install pyright

# Linting
npm install -g eslint

# Rust
# 下载 rust-analyzer: https://github.com/rust-lang/rust-analyzer/releases

---

7. Agent 使用 Demo

7.1 内置 Agent

Agent	类型	功能	调用方式
Build	主 Agent	全部工具，负责编码	默认 / Tab 切换
Plan	主 Agent	只读分析，制定计划	Tab 切换到 Plan 模式
General	子 Agent	复杂搜索多步任务	@general 帮我搜索...
Explore	子 Agent	快速探索代码库	@explore 找认证模块...
Scout	子 Agent	外部文档/依赖研究	@scout 查某个库用法...

7.2 创建自定义 Agent

方式一：命令行创建

opencode agent create

交互式问答自动生成 Agent 配置文件。

方式二：手动创建

在项目 .opencode/agents/ 目录下创建 .md 文件：

.opencode/agents/code-reviewer.md：

---
description: 审查代码质量和安全问题
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff *": allow
    "grep *": allow
---
你是代码审查专家。关注安全漏洞、性能问题、代码规范。

输出格式：按严重度分类（高危/中危/低危），每项附带文件路径和行号。

7.3 多 Agent 协作工作流

# 第一步：用 Plan Agent 制定计划
# 按 Tab 切换到 Plan，描述需求

# 第二步：用 Build Agent 实现
# 按 Tab 切回 Build，说"按照计划开始开发"

# 第三步：并行委派子Agent
@general 检查所有使用了旧API的文件
@explore 查看认证模块的实现
@code-reviewer 审查刚写完的代码

# 第四步：验证和测试
@test-writer 为新代码编写测试

7.4 Agent 导航键位

操作	快捷键
切换主 Agent	Tab
@mention 子 Agent	@
进入第一个子会话	<Leader> + ↓
切换子会话	→ / ←
返回父会话	↑

7.5 完整 Agent 套件配置

{
  "agent": {
    "api-designer": {
      "description": "设计 RESTful API 接口",
      "mode": "subagent",
      "permission": { "edit": "allow", "bash": "deny" },
      "prompt": "你是API设计专家。输出OpenAPI规范文档。"
    },
    "db-designer": {
      "description": "设计数据库表结构",
      "mode": "subagent",
      "permission": { "edit": "allow", "bash": "deny" },
      "prompt": "你是数据库设计专家。输出完整DDL脚本。"
    },
    "backend-dev": {
      "description": "后端业务逻辑开发",
      "mode": "subagent",
      "permission": { "bash": { "grep *": "allow", "*": "ask" } },
      "prompt": "你是后端开发专家。遵循项目现有架构模式进行开发。"
    },
    "frontend-dev": {
      "description": "前端组件和页面开发",
      "mode": "subagent",
      "permission": { "bash": "deny" },
      "prompt": "你是前端开发专家。遵循项目UI框架和代码风格。"
    },
    "code-reviewer": {
      "description": "代码质量和安全审查",
      "mode": "subagent",
      "permission": { "edit": "deny" },
      "prompt": "审查代码的质量、安全、性能问题，输出分类报告。"
    },
    "security-auditor": {
      "description": "安全漏洞审计",
      "mode": "subagent",
      "permission": { "edit": "deny" },
      "prompt": "审计依赖漏洞、注入风险、认证缺陷，按CVSS排序。"
    },
    "test-writer": {
      "description": "编写单元测试和集成测试",
      "mode": "subagent",
      "permission": { "bash": { "*": "allow" } },
      "prompt": "先检查项目测试框架配置，编写符合现有模式的测试。"
    },
    "docs-writer": {
      "description": "编写技术文档",
      "mode": "subagent",
      "permission": { "edit": "allow", "bash": "deny" },
      "prompt": "编写清晰的技术文档，含代码示例。"
    },
    "debugger": {
      "description": "调试和修复bug",
      "mode": "subagent",
      "permission": { "bash": { "grep *": "allow", "git *": "allow", "*": "ask" } },
      "prompt": "先定位根因再修复，确保不引入新问题。"
    },
    "devops": {
      "description": "CI/CD和Docker配置",
      "mode": "subagent",
      "permission": { "bash": { "docker *": "allow", "git *": "allow", "*": "ask" } },
      "prompt": "配置Docker部署和CI/CD pipeline。"
    }
  }
}

---

8. 故障排查

启动报错

# 检查 Node.js 版本
node -v   # 需要 >= 18

# 重新安装
npm uninstall -g opencode-ai
npm install -g opencode-ai

API 连接失败

// 确认 opencode.json 中 baseURL 正确
"baseURL": "https://api.lkeap.cloud.tencent.com/plan/v3"

模型列表为空

# 启动 opencode 后
/models   # 刷新模型列表

开启调试日志

$env:OPENCODE_LOG_LEVEL = "debug"
opencode

配置文件位置

类型	路径
全局配置	C:\Users\<用户名>\.config\opencode\opencode.json
项目配置	<项目根目录>\opencode.json
全局 Agent	C:\Users\<用户名>\.config\opencode\agents\
项目 Agent	<项目根目录>\.opencode\agents\
全局 Skills	C:\Users\<用户名>\.config\opencode\skills\
项目 Skills	<项目根目录>\.opencode\skills\
全局 Commands	C:\Users\<用户名>\.config\opencode\commands\
项目 Commands	<项目根目录>\.opencode\commands\
认证凭据	C:\Users\<用户名>\.local\share\opencode\auth.json

---

快速验收

1. 启动：opencode → 进入 TUI 界面
2. 输 /models → 看到腾讯云模型列表
3. 选择模型 → 输入 "创建一个 Hello World 函数"
4. 输入 /help → 查看可用命令