前言

OpenCode 是一款开源的 AI 编码代理（AI coding agent），提供终端 CLI、桌面应用和 IDE 扩展三种形态。本文手把手教你在 macOS / Linux / Windows 上安装 OpenCode CLI，讲清安装前的前置条件，并重点介绍它强大的插件（Plugin）生态——插件能做什么、去哪里找、到底怎么装。

官网：OpenCode | The open source AI coding agent 官方文档：Intro | AI coding agent built for the terminal

一、安装前的准备工作（前置条件）

在开始安装前，请先确认以下条件：

• 现代终端模拟器：例如 WezTerm、Alacritty、Ghostty、Kitty 等。Windows 用户建议使用 WSL。
• Node.js（可选）：如果用 npm 方式安装，需要 Node.js v18+。
• 至少一个 LLM 提供商的 API Key：OpenCode 本身不绑定模型，需要你提供模型访问方式。官方推荐使用 OpenCode Zen：Zen | OpenCode
• 网络环境：安装脚本与 npm 安装都需要访问外网；国内用户可先设置 npm 镜像源加速。

如果你用 npm 安装，可先执行下面命令换源加速：

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

二、安装 OpenCode CLI（多平台）

方法一：官方一键安装脚本

脚本会自动识别你的系统与架构，并把二进制加入 PATH：

curl -fsSL https://opencode.ai/install | bash

方法二：Node.js 包管理器（npm / Bun / pnpm / Yarn）

补充：用 npm 安装前，先配好 Node.js 环境（建议装到 D 盘）

如果你选择用npm（或 pnpm / yarn / bun）方式来安装 OpenCode，就必须先装好 Node.js（官方要求 v18 及以上，推荐直接用 LTS 版）。这里最关键的两点是：到官网下载，并且把 Node.js 安装到 D 盘，避免占用日益紧张的系统 C 盘空间。

1）Node.js 官方下载地址

打开 Node.js 官网中文下载页：Node.js — 下载 Node.js® ，选择LTS（长期支持版）下的Windows 安装包（.msi），例如node-v20.xx.x-x64.msi。

2）安装到 D 盘，而不是 C 盘

双击运行下载好的 .msi 安装包，在安装向导里把安装目录（Destination Folder）从默认的C:\Program Files\nodejs\改成 D 盘路径，例如：

D:\Dev\nodejs\

安装界面记得勾选“Add to PATH”（加入环境变量）。安装完成后，建议再把 npm 的全局包目录和缓存目录也一起改到 D 盘，重新打开一个终端执行：

npm config set prefix "D:\Dev\nodejs\npm-global" npm config set cache "D:\Dev\nodejs\npm-cache"

3）验证 Node.js 与 npm 是否安装成功

重新打开一个新的终端（让 PATH 生效），输入：

node -v npm -v

能分别打印出版本号（例如v20.x.x与10.x.x）就说明环境已经装好，此时再回到上面的 npm 命令安装 OpenCode 即可。

npm install -g opencode-ai bun install -g opencode-ai pnpm install -g opencode-ai yarn global add opencode-ai

方法三：Homebrew（macOS / Linux）

brew install anomalyco/tap/opencode

官方推荐使用 OpenCode tap 以获取最新版本。

方法四：Arch Linux

sudo pacman -S opencode # 稳定版 paru -S opencode-bin # AUR 最新版

方法五：Windows

官方推荐使用 WSL 获得最佳体验（Windows (WSL) | OpenCode）；也可用原生包管理器：

choco install opencode scoop install opencode npm install -g opencode-ai

方法六：Docker

docker run -it --rm ghcr.io/anomalyco/opencode

方法七：桌面版（Beta）

brew install --cask opencode-desktop

或从下载页获取：OpenCode | Download

验证安装

opencode --version

能输出版本号即安装成功。

三、配置模型与初始化

在 TUI 中运行/connect，选择 opencode，然后前往 OpenAuth 登录、复制 API Key 并粘贴即可。也可以配置其他提供商：Providers | OpenCode

进入项目目录并启动：

cd /path/to/project opencode /init

/init会分析项目并生成 AGENTS.md，官方建议提交到 Git，帮助 OpenCode 理解项目结构与规范。

常用命令与用法（Slash 命令 / CLI 命令）

OpenCode 的命令分为两类：一类是在交互式界面（TUI）中以/开头的 Slash 命令，另一类是在终端中直接执行的 CLI 命令。下面分别整理。

1）TUI 内的 Slash 命令（进入 opencode 界面后输入/即可触发，部分命令带ctrl+x快捷键）：

• /init：分析当前项目并生成或更新 AGENTS.md 文件（初始化项目，最常用）。
• /connect：添加模型提供商并配置 API Key。
• /models：列出并切换可用模型。
• /new（别名/clear）：新建一个会话。
• /sessions（别名/resume、/continue）：查看并切换历史会话。
• /compact（别名/summarize）：压缩当前会话上下文，节省 Token。
• /undo//redo：撤销 / 重做上一步操作（包含文件改动，依赖 Git 仓库）。
• /share//unshare：分享 / 取消分享当前会话。
• /editor：调用外部编辑器编写提示词。
• /export：把当前对话导出为 Markdown。
• /theme：切换界面主题。
• /thinking：显示或隐藏模型的思考过程。
• /help：查看帮助。
• /exit（别名/quit、/q）：退出。

2）Agent（智能体）用法：

• 切换主智能体：在 TUI 中按Tab/Shift+Tab。内置 build（默认，可读写文件、执行命令）与 plan（只读，用于分析与规划）两个主智能体。
• 调用子智能体：在消息中用@名称提及，例如@explore、@general、@scout。
• 管理智能体：在终端执行opencode agent create创建自定义智能体，opencode agent list列出全部智能体。

3）常用 CLI 命令（在终端中执行）：

• opencode：启动 TUI 交互界面。
• opencode run "你的指令"：非交互模式，执行一条指令后退出。
• opencode auth login：配置模型提供商的登录凭证。
• opencode models：列出当前可用的模型。
• opencode mcp add/opencode mcp list：添加 / 查看 MCP 服务器。
• opencode session list：列出历史会话。
• opencode stats：查看 Token 用量与费用统计。
• opencode upgrade：升级到最新版本。
• opencode --version：查看当前版本。

小提示：在消息中输入@文件路径可引用项目文件；以!开头可直接执行 shell 命令并把输出加入对话。例如：

@explore 找出所有写入 users 表的代码路径 !git status

以上命令均整理自 OpenCode 官方文档，具体以官方最新版本为准。

四、OpenCode 的插件系统

插件（Plugin）是 OpenCode 最强大的扩展能力：它允许你通过挂钩（hook）各种事件来扩展或改变 OpenCode 的默认行为——添加新功能、对接外部服务、注入上下文，甚至给 AI 添加自定义工具。

插件官方文档：Plugins | OpenCode

插件生态总览（含全部插件与地址）：Ecosystem | OpenCode

4.1 插件的两种安装方式

方式 A：从本地文件加载。把 .js / .ts 插件文件放进插件目录，启动时会自动加载：

.opencode/plugins/ # 项目级插件 ~/.config/opencode/plugins/ # 全局插件

方式 B：从 npm 加载。在配置文件 opencode.json 中声明包名即可：

{ "$schema": "https://opencode.ai/config.json", "plugin": ["opencode-wakatime", "opencode-notify"] }

npm 插件会在启动时由 Bun 自动安装，依赖缓存在 ~/.cache/opencode/node_modules/。支持普通包与作用域包（如 @scope/plugin）。

4.2 插件加载顺序

• 全局配置 ~/.config/opencode/opencode.json
• 项目配置 opencode.json
• 全局插件目录 ~/.config/opencode/plugins/
• 项目插件目录 .opencode/plugins/

4.3 插件推荐（附地址）

OmO（Oh My OpenCode，即 oh-my-opencode）

OmO 是当前 OpenCode 生态里一个功能比较全面的增强插件：作者把 AmpCode、Claude Code 中最好用的能力搬了过来并做了加强，相当于把 OpenCode 直接升级成一个多智能体（Multi-Agent）开发

主要特性：

• 后台并行智能体：主代理 Sisyphus 负责统筹，会像真实开发团队一样并行派出子代理——Hephaestus（自主深度执行）、Oracle（架构 / 调试）、Librarian（查官方文档与开源实现）、Explore（极速代码库检索）等，主代理上下文不再被塞爆。
• 预置 LSP / AST 工具：重构、重命名、诊断、AST 感知的代码搜索都更精准、更安全，改代码不再"蒙着眼睛"。
• 内置 MCP：开箱即用的 websearch（Exa）、context7（官方文档）、grep_app（GitHub 代码搜索）。
• Claude Code 兼容层：支持 Command、Agent、Skill、MCP，以及 PreToolUse / PostToolUse / UserPromptSubmit / Stop 等 Hook。
• 魔法关键词：在提示词里加上ulw（ultrawork），即可自动触发并行智能体、后台任务与深度探索，并且"不干完不罢休"。
• 贴心小功能：TODO 强制完成（半途而废会被拉回来继续做）、注释检查（避免 AI 堆砌无意义注释）、会话记忆等。

项目地址：GitHub - code-yeongyu/oh-my-openagent: OmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering. · GitHub

安装方式与上面 4.1 一致：把oh-my-opencode加入opencode.json的plugin数组即可；官方也建议直接让 AI 代理按仓库说明自动完成安装与配置。

• opencode-notify——任务完成时发送原生系统通知：GitHub - kdcokenny/opencode-notify: Native OS notifications for OpenCode – know when tasks complete · GitHub
• opencode-wakatime——用 WakaTime 统计你的编码时长：GitHub - angristan/opencode-wakatime: Track Opencode usage with Wakatime · GitHub
• opencode-morph-fast-apply——借助 Morph 让代码编辑快 10 倍：GitHub - JRedeker/opencode-morph-fast-apply: OpenCode plugin for Morph Fast Apply - 10x faster code editing with lazy edit markers. No MCP server needed. · GitHub
• opencode-dynamic-context-pruning——裁剪过期的工具输出，节省 Token：GitHub - Tarquinen/opencode-dynamic-context-pruning: Dynamic context pruning plugin for OpenCode - intelligently manages conversation context to optimize token usage · GitHub
• opencode-supermemory——跨会话的持久记忆：GitHub - supermemoryai/opencode-supermemory: Supermemory plugin for OpenCode · GitHub
• oh-my-opencode——后台代理 + 预置 LSP/AST/MCP 工具，兼容 Claude Code：GitHub - code-yeongyu/oh-my-openagent: OmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering. · GitHub
• opencode-openai-codex-auth——直接用你的 ChatGPT Plus/Pro 订阅，而非 API 计费：GitHub - numman-ali/opencode-openai-codex-auth: OAuth authentication plugin for personal coding assistance with ChatGPT Plus/Pro subscriptions - uses OpenAI's official authentication method · GitHub
• opencode-gemini-auth——复用已有的 Gemini 套餐：GitHub - jenslys/opencode-gemini-auth: Gemini auth plugin for opencode · GitHub
• opencode-firecrawl——网页抓取、爬取与搜索：GitHub - firecrawl/opencode-firecrawl · GitHub
• opencode-websearch-cited——为支持的模型加入原生联网搜索（带引用）：GitHub - ghoulr/opencode-websearch-cited: An OpenCode plugin that provides LLM cited web search. · GitHub
• opencode-pty——让 AI 在 PTY 中运行后台进程并发送交互输入：GitHub - shekohex/opencode-pty: OpenCode plugin for interactive PTY management - run background processes, send input, read output with regex filtering · GitHub
• opencode-vibeguard——在调用 LLM 前对密钥/隐私信息做脱敏：GitHub - inkdust2021/opencode-vibeguard: VibeGuard for opencode · GitHub
• opencode-worktree——零成本的 git worktree 工作流：GitHub - kdcokenny/opencode-worktree: Zero-friction git worktrees for OpenCode. Auto-spawns terminals, syncs files, cleans up on exit. · GitHub
• opencode-md-table-formatter——清理 LLM 生成的 Markdown 表格：GitHub - franlol/opencode-md-table-formatter: Markdown table formatter plugin for OpenCode with concealment mode support. · GitHub
• opencode-type-inject——读取文件时自动注入 TypeScript/Svelte 类型：GitHub - nick-vi/type-inject: TypeScript type context for AI coding assistants. Auto-injects type signatures on reads, reports type errors on writes, and provides type lookup tools. · GitHub
• @openspoon/subtask2——把 /commands 扩展为强大的编排系统：GitHub - spoons-and-mirrors/subtask2: A stronger opencode /command handler · GitHub

五、相关链接汇总

• 官网首页：OpenCode | The open source AI coding agent
• 官方文档（简介 / 安装）：Intro | AI coding agent built for the terminal
• 官方下载页：OpenCode | Download
• 插件文档：Plugins | OpenCode
• 插件生态总览：Ecosystem | OpenCode
• Windows + WSL 指南：Windows (WSL) | OpenCode
• 提供商目录：Providers | OpenCode
• GitHub 仓库：GitHub - anomalyco/opencode: The open source coding agent. · GitHub
• GitHub Releases：Releases · anomalyco/opencode · GitHub

小结

安装 OpenCode CLI 只需一条命令即可完成，真正让 OpenCode 变强的是它的插件生态。建议先装好 opencode-notify、opencode-wakatime 等基础插件，再按需加入 fast-apply、上下文裁剪、持久记忆等进阶插件，打造属于你自己的 AI 编程工作流。

说明：本文安装指令与插件信息整理自 OpenCode 官方网站与官方文档，插件地址均来自官方生态页；工具更新较快，具体命令请以官方文档最新版本为准。