← Windows下OpenCode的安装与配置

Windows下OpenCode的安装与配置（一）——前言与安装

Windows下OpenCode的安装与配置 2026-04-16 3 0
OpenCode AI CLI 效率工具 教程

为什么我要用 OpenCode

说起 AI 编程助手，大多数人第一反应是 GitHub Copilot 或者 Cursor。它们确实好用，但有一个共同点：都是 GUI 编辑器的附属品。你得打开一个特定的编辑器，才能用上 AI 能力。

我想要的不是"在某个编辑器里用 AI"，而是一个独立的 AI 编程终端。它不绑定任何编辑器，可以直接在命令行里读代码、改代码、跑命令、做 Code Review、写文档。不管你用 VS Code、Vim 还是 Notepad++，都不影响它工作。

OpenCode 就是这样一个工具。它是一个开源的 AI CLI（命令行界面），由 SST（Serverless Stack）团队开发，定位是"终端里的 AI 编程助手"。你可以把它理解成一个跑在终端里的 Claude Code / Cursor，但更灵活、更可控。

OpenCode 能干什么

在开始装之前，先说清楚它到底能帮你干什么，免得装完了不知道怎么用。

  • 直接在终端里跟 AI 对话，让它读你的代码、回答问题、写代码
  • 自动读取整个项目结构，AI 能理解你的代码上下文
  • 直接编辑文件，AI 不只是给建议，它能帮你直接改代码
  • 执行终端命令，比如跑测试、装依赖、Git 操作
  • 支持多种 AI 模型，Claude、GPT、Gemini 都可以接，甚至支持第三方中转站
  • 插件系统，可以通过插件扩展能力，比如 Oh My OpenCode 能加入多智能体协作
  • Skills 系统，可以给 AI 装"技能包"，让它在特定领域表现更好

简单说，它不是一个只能聊天的 AI，而是一个能真正动手干活的 AI 代理。

这个系列会写什么

这个系列一共 3 篇，按从安装到完全可用的顺序来写：

1. 前言与安装（本篇）

把 OpenCode 装起来，确保它能正常启动。

2. 配置与模型接入

配置 opencode.json，接入 AI 模型，包括官方 API 和第三方中转站的配置方式。

3. Oh My OpenCode 插件与 Skills 安装

安装 Oh My OpenCode 插件获得多智能体能力，再装一批实用 Skills 让 AI 更专业。

不需要你有任何 AI 工具的使用经验，也不需要你很懂命令行。跟着来，装完就能用。

安装前的准备

在装 OpenCode 之前，你需要先确认这几样东西已经就位。

1. Node.js

OpenCode 通过 npm 安装，所以你需要先有 Node.js。

前往 Node.js 官网 下载 LTS 版本，安装时一路默认即可。安装完成后打开终端确认：

node --version
# 输出示例：v24.13.0

npm --version
# 输出示例：11.6.2

建议：Node.js 版本不要低于 18，推荐直接装最新 LTS。

2. Git

OpenCode 的很多功能依赖 Git，尤其是项目上下文读取和 GitHub 集成。

前往 Git 官网 下载 Windows 安装包。安装时注意以下两点：

  • 在 Adjusting your PATH environment 步骤，选择 Git from the command line and also from 3rd-party software
  • 其他选项保持默认即可

安装后确认：

git --version
# 输出示例：git version 2.47.1.windows.2

重要提示：安装 Git 时会自带一个 Git Bash。OpenCode 在 Windows 上执行 Shell 命令时需要用到它。通常安装完 Git 后 OpenCode 能自动找到 Git Bash，如果后面遇到命令执行报错，可以手动设置环境变量：

# 在系统环境变量中添加
OPENCODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe

3. 一个现代终端

OpenCode 的 TUI（终端界面）需要一个支持现代渲染的终端。推荐使用 Windows Terminal，它是 Windows 11 自带的，Windows 10 可以在 Microsoft Store 里免费安装。

不要用 CMD，体验会很差。PowerShell 配合 Windows Terminal 是最稳的组合。

4. AI 模型的 API Key

OpenCode 本身不提供 AI 模型，它需要你自己接入。你至少需要以下其中一个：

API Key 现在不用急着准备，下一篇配置的时候再填。但你要确保能拿到至少一个可用的 Key。

安装 OpenCode

准备工作做完了，正式开始装。

方法一：npm 全局安装（推荐）

打开 Windows Terminal，执行：

npm install -g opencode-ai

等它装完后确认：

opencode --version
# 输出示例：1.2.27

看到版本号就说明安装成功了。

镜像加速：如果你在国内，npm 下载可能很慢，可以先换成淘宝镜像：

npm config set registry https://registry.npmmirror.com
npm install -g opencode-ai

方法二：通过包管理器安装

如果你已经在用 Scoop 或 Chocolatey，也可以用它们来装：

# Scoop
scoop install opencode

# Chocolatey
choco install opencode

方法三：直接下载二进制

前往 OpenCode GitHub Releases 页面，下载 Windows 对应的 .exe 文件，放到 PATH 目录下即可。

三种方式效果一样，选你顺手的就行。我个人推荐 npm 方式，因为后续升级最方便，一条命令搞定：

opencode upgrade

验证安装

装完之后，先别急着配置，跑一下确认它能启动。

在终端输入：

opencode --help

你应该能看到类似这样的输出：

Commands:
  opencode completion          generate shell completion script
  opencode mcp                 manage MCP (Model Context Protocol) servers
  opencode [project]           start opencode tui
  opencode run [message..]     run opencode with a message
  opencode providers           manage AI providers and credentials
  opencode agent               manage agents
  opencode upgrade [target]    upgrade opencode to the latest version
  opencode models [provider]   list all available models
  opencode stats               show token usage and cost statistics
  ...

如果看到这个输出，说明 OpenCode 已经成功安装。

现在试着直接输入 opencode 启动 TUI 界面。第一次启动时，它会提示你还没有配置任何 AI 模型，这很正常，因为我们还没有写配置文件。按 Ctrl+C 退出即可。

OpenCode 的目录结构

在继续配置之前，先搞清楚 OpenCode 的文件放在哪里，后面改配置时你不会到处找。

路径 作用
C:\Users\你的用户名\.config\opencode\ 全局配置目录
C:\Users\你的用户名\.config\opencode\opencode.json 主配置文件
C:\Users\你的用户名\.config\opencode\local-plugins\ 本地插件目录
C:\Users\你的用户名\.agents\skills\ Skills 技能包目录
项目根目录下的 opencode.json 项目级配置（覆盖全局）

知道这几个路径就够了，下一篇配置的时候会逐个用到。

小结

至此我们完成了：

  1. 环境准备 — Node.js、Git、Windows Terminal
  2. OpenCode 安装 — 通过 npm 全局安装
  3. 安装验证 — 确认命令行可用
  4. 目录结构 — 知道配置文件放在哪

这篇只管"装上"，下一篇开始配模型、接 API，让 OpenCode 真正能跟你对话。

目录

Comments (0)

No comments yet. Be the first!