OpenCode 是一个开源的 AI 编程助手（Coding Agent），提供免费模型（如 DeepSeek、Minimax），也支持通过 API Key 接入其他模型。本文是完整的安装、配置到进阶使用指南。

一、什么是 OpenCode

OpenCode 是一个开源的 AI 编程助手（Coding Agent），提供免费模型（如 DeepSeek、Minimax），也支持通过 API Key 接入其他模型。

核心能力：你通过自然语言给它下达编程任务，它自主阅读代码库、理解项目结构、编写/修改代码、执行命令，并在过程中通过 Agent 系统委派子任务。

OpenCode 基于 Node.js 构建，使用 npm 安装。

二、安装

2.1 安装 Node.js

OpenCode 是 npm 包，依赖 Node.js 运行时。

1. 前往官网 https://nodejs.org/ 下载 LTS（长期支持版） 安装包
2. Windows 选 .msi，双击安装，一路默认即可
3. 安装后打开终端验证：

1

node --version

返回版本号（如 v20.x.x）即成功。

Windows 用户安装时会自动添加系统 PATH，安装后若 node 找不到，重启终端再试。

2.2 安装 OpenCode

确保 Node.js 安装完成后，执行：

1

npm install -g opencode-ai

Windows 用户：以管理员身份运行 PowerShell（右键开始菜单 → 终端(管理员)），再执行上述命令。

网络慢时可切换 npm 镜像源：

1	npm config set registry https://registry.npmmirror.com

验证安装：

1

opencode --version

返回版本号即成功。

三、快速上手

3.1 启动

在终端输入 opencode 即可进入交互界面：

1

opencode

首次启动建议执行：

• 使用 /model 命令选择模型（如 DeepSeek 或 Minimax）
• 直接提问，例如”当前目录有哪些文件”或”帮我配置项目”

3.2 基本交互模式

四、配置详解

4.1 配置目录结构

OpenCode 的配置存放在用户目录下的 .config/opencode：

该目录的典型结构：

1
2
3
4
5
6

.config/opencode/
├── opencode.json          # 主配置文件（模型、插件、LSP 等）
├── AGENTS.md              # 全局记忆文件（静默加载的系统指令）
├── plugins/               # 插件安装目录
├── skills/                # 技能包安装目录
├── node_modules/          # 插件依赖

4.2 opencode.json（主配置文件）

配置文件采用 JSON 格式，示例结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/deepseek-v4-flash-free",
  "plugin": [
    "oh-my-openagent@latest",
    "@tarquinen/opencode-dcp@latest",
    "opencode-supermemory@latest"
  ],
  "instructions": [
    "C:\\Users\\你的用户名\\.config\\opencode\\AGENTS.md"
  ],
  "lsp": {
    "basedpyright": {
      "command": ["basedpyright-langserver", "--stdio"],
      "extensions": [".py"]
    }
  }
}

修改方式：可以直接编辑该文件，也可以在 OpenCode 对话中让它帮你改。

4.3 AGENTS.md（记忆/指令文件）

AGENTS.md 是 OpenCode 的静默加载指令文件，OpenCode 在每次对话中会自动读取其中的内容作为系统指令。

加载规则：

• 全局 ~/.config/opencode/AGENTS.md — 所有项目通用
• 项目级 项目目录/AGENTS.md — 仅当前项目生效
• 优先级：项目级 > 全局级（同名指令项目级覆盖全局级）

文件必须命名为 AGENTS.md（全大写），Agent.md、agents.md 等不会被自动识别。

典型用法：在 AGENTS.md 中写入项目结构说明、编码规范、工具偏好等信息，让 OpenCode 每次都能参考。

4.4 工作目录与权限模型

工作目录 = 你运行 opencode 命令时所在的目录。

• OpenCode 默认能自由读写工作目录及其子目录内的所有文件
• 跨目录读写文件时，会询问你确认
• 你可以在对话中通过 /allow 授权特定目录访问，或在配置文件中提前设置

重要：工作目录 ≠ 配置目录（~/.config/opencode）。你在哪里运行 opencode，哪里就是工作目录。

五、插件

安装方法

在 OpenCode 对话中直接说：

1

安装插件 [包名]

它会自动执行安装并配置。以下是推荐插件：

oh-my-openagent@latest

安装后解锁 OpenCode 的 Agent 系统。部分 Agent 通过 /agents 列表展示，还有一些（如 oracle、explore、librarian）在代码中通过 task(subagent_type="xxx") 调用。在 OpenCode 中问”我有哪些 Agent”即可查看。

opencode-supermemory@latest

持久化记忆插件，让 OpenCode 能跨会话、跨项目”记住”信息。安装后需要 API Key（免费额度够用）：

1. 前往 https://app.supermemory.ai/?view=integrations 获取 API Key
2. 在 OpenCode 对话中说”帮我配置 Supermemory API Key”
3. 粘贴 API Key，OpenCode 会自动写入配置文件

提供 5 种操作模式（直接在对话里用自然语言说即可）：

@tarquinen/opencode-dcp@latest

自动上下文窗口管理。把对话中旧的、不再需要的内容压缩成摘要，避免上下文被撑爆。无需手动操作，安装即生效。

六、MCP（Model Context Protocol）

6.1 概念

MCP（Model Context Protocol，模型上下文协议）可以理解为 AI 应用的”USB-C 接口”。

它解决的核心问题是：不同 AI 客户端（OpenCode、Claude Code、Cursor 等）对接不同数据源（数据库、文件系统、浏览器等）时，集成代码散的到处都是的碎片化问题。

• 没有 MCP 之前：每个 AI 客户端接入一个新的数据源/工具，都要自己写一套集成代码。查数据库写一套、操作浏览器写一套，换个 AI 客户端还得重新写一遍。
• 有了 MCP 之后：数据源/工具方只需实现一个 MCP Server，所有支持 MCP Client 的 AI 应用都能直接对接，无需重复开发。

6.2 配置方式

MCP Server 的配置写在 opencode.json 的 mcp_servers 字段中。

方式一：本地 Stdio 模式

通过命令启动，数据通过标准输入输出传输：

1
2
3
4
5
6
7
8

{
  "mcp_servers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@某个/mcp-server"]
    }
  }
}

方式二：远程 SSE 模式

连接到远程服务器的 URL，支持服务器主动推送：

1
2
3
4
5
6
7

{
  "mcp_servers": {
    "my-server": {
      "url": "http://your-server:3000/sse"
    }
  }
}

6.3 推荐 MCP 服务

Playwright — 浏览器自动化，可用于在线考试、问卷填写、文档爬取等。

配置方式：让 OpenCode 安装即可。在对话中说”配置 Playwright MCP”，它会自动安装浏览器驱动并写入配置。

Context7 — 实时查询最新库文档，避免 AI 因训练数据过时而给出过时 API。

配置方式（需 API Key，免费额度够用）：

1. 前往 https://context7.com 注册并获取 API Key
2. 在 OpenCode 对话中说”帮我配置 Context7 API Key”
3. 粘贴 API Key，OpenCode 会自动写入配置

更多 MCP Server 可在 https://github.com/modelcontextprotocol/servers 探索。

七、Skills（技能包）

Skills 是技能包——为 AI 注入特定领域知识的说明书。装上一个技能包，AI 就”学会”了该领域的规范和最佳实践。

安装方法

在 OpenCode 对话中说”帮我安装技能”，粘贴技能包的 GitHub 地址即可。

推荐 Skill（计算机专业学生版）

通用必修：

按需选修：

更多 Skills 可在 OpenCode 社区或 GitHub 搜索 opencode-skill 查找。

八、常用命令

更多命令可在 OpenCode 中直接输入 / 查看自动补全列表。

附录：工具链推荐

以下工具与 OpenCode 配合使用效果较好。建议将其写入全局 AGENTS.md，让 OpenCode 每次自动知晓你的工具偏好。

yt-dlp

下载 B 站、YouTube 等视频网站的视频。命令行工具，支持格式选择和字幕下载。

python-docx

Python 库，用于读取、创建和修改 .docx 文件。

配置记忆方法

在全局 ~/.config/opencode/AGENTS.md 中写入类似内容：

1
2
3

全局工具偏好：
- 视频下载优先用 yt-dlp
- Word 文档操作使用 python-docx

写入后 OpenCode 每次都会参考这些偏好，无需重复说明。

封面图：遮风壁纸 · 雪地仙境
文章插图：遮风壁纸 · 品牌标识 & 原野白雾