前两篇文章，我们聊了两件挺有冲击力的事：一位顶尖经济学家让 AI 一个月自主产出 230 篇实证论文（《当 AI 开始自己写论文》），一位计量经济学家用 Claude Code 搭了一整套科研和教学的自动化系统（《一位计量经济学家的 Claude Code 工作流》）。

两篇发出来之后，后台收到最多的一个问题——这个 Claude Code 到底怎么装？

说实话，Claude Code 在国内几乎没法用。Anthropic 不对中国区开放，已有账号也时不时被封；全程需要特殊网络环境，光配网络就能劝退大部分人。

但好消息是，现在有了一个几乎完美的开源平替——Opencode。

这个项目在 GitHub 上已经超过 100k 星、700 多位贡献者，每月有 250 万开发者在用，是目前最火的开源 AI 编程助手。它完全具备 Claude Code 的核心功能——终端运行、读写本地文件、执行命令、自然语言操控——同时对国内用户有几个决定性的优势：

• 不需要任何特殊网络设置，国内直接用
• 支持 75+ 模型供应商，包括国内的智谱 AI、Kimi、MiniMax、DeepSeek，想用哪家用哪家
• 自带免费模型，连注册都不用，开箱即用

换句话说，前两篇文章里展示的那些能力——AI 直接在你电脑上干活、处理文件、写代码、做分析——用 Opencode 配合国内模型，完全可以实现。

不过很多人卡在了第一步：装了个 AI，打开一看——不会用终端，缺这个依赖，少那个环境，折腾半天没跑起来。问题出在哪？光装 AI 本身没用，你还需要一整套配合它的工具链。

于是有了这篇 1.2 万字的 AI 套装安装配置教程，面向完全零基础的小白读者。

你不用再去网上找其他安装教程了，这篇文章帮你一次性搞定全套。装完之后，你的电脑上会多出一个完整的 AI 生产力工具链：

• Opencode（AI 本体）：在终端里跟你对话、帮你读写文件、执行各种操作
• VS Code（工作台）：看文件、改文件，和 AI 在同一个窗口里协作
• 程序环境（conda、Git、Node.js、Pandoc）：Python 数据分析、版本管理、文档格式转换——AI 干活要调用的底层能力，全靠这些
• 15 个实用 Skills（技能扩展包）：Word 处理、PDF 操作、幻灯片制作、网页抓取……装上就能用的现成技能

不只是“装个 AI 聊天工具”，而是配齐一整套能处理实际工作的装备。

零基础也能跟着做。 教程从“终端怎么打开”讲起，每一步都有截图，每个命令都解释了是什么意思，装完还有验证步骤。最后还会带你认识 VS Code 界面和 Opencode 的操作方法，让你装完就能上手。

Mac 和 Windows 各有专属章节，按你的系统选读就行。整个过程大约 30-60 分钟。

教程版本：2026-02-22 | 适用系统：macOS（Intel 和 Apple Silicon）/ Windows 10 / Windows 11

目录

第一部分：macOS 用户（第 1-5 步）

• 认识终端 → Xcode 命令行工具
• Homebrew
• 使用 brew 一键安装所有工具 → 必要配置
• 各工具简介
• macOS 常见问题解答

第二部分：Windows 用户（第 1-9 步）

• 认识 PowerShell → 设置执行策略
• Git → 配置 Git
• Node.js → Opencode
• VS Code → Miniconda → Pandoc
• Windows 日常使用快速参考

第三部分：通用配置（Mac / Windows 相同）

• 安装 Skills 扩展包（使用 Opencode 自带免费模型）
• 配置 API 密钥（可选，推荐）
• 全部完成！下一步

第四部分：在 VS Code 中使用 Opencode

• 认识 VS Code 界面 → 安装推荐插件 → 打开工作文件夹 → 打开内置终端
• 启动 Opencode → 基本操作速查

安装清单总览

安装完成后，你将拥有以下全套工具：

第一部分：macOS 用户

写在前面

安装完成后，你将拥有一套完整的 AI 工作环境：

• Opencode：在终端中运行的 AI 助手，能帮你处理文件、写代码、做分析
• VS Code：强大的文本编辑器，配合 AI 使用效果更好
• Python 环境：用于数据分析和自动化任务
• 一批实用工具：Git、Pandoc 等

整个安装过程大约需要 60 分钟。请按顺序操作，不要跳步。

Mac 安装的核心思路：先装好 Homebrew（相当于 Mac 的“应用商店”），之后所有软件都一行命令搞定，不用再手动下载安装包。

第 1 步：认识终端

终端是什么

终端（Terminal）是 macOS 里一个特殊的应用，你在里面输入文字命令，电脑就按命令执行。

和平时点击图标操作不一样，这里靠“打字”来控制电脑。别害怕，命令都是英文单词，看着陌生，用着简单。

怎么打开终端

最快的方法：Spotlight 搜索

1. 同时按下键盘上的 Command（⌘）键 + 空格键
2. 屏幕中间会弹出一个搜索框
3. 输入 Terminal（终端）
4. 看到“终端”或“Terminal.app”出现在结果列表
5. 按回车键，或者用鼠标双击它

终端打开后，你会看到一个窗口，里面有一行文字，类似这样：

这行文字叫做“提示符”，意思是电脑在等你输入命令。~ 表示你现在在“家目录”（你自己的文件夹），% 是光标所在位置。

终端基本操作

学会这几个动作，就够用了：

小提示：输入命令时不要加引号，除非教程里明确要求。

第 2 步：安装 Xcode 命令行工具

为什么需要它

macOS 自带的系统里缺少很多开发者工具，比如 Git、编译器等。Xcode 命令行工具是苹果官方提供的工具包，安装后这些工具就有了。

后面安装 Homebrew、Node.js 等软件都依赖它。这是基础，必须先装。

注意：这里安装的是“命令行工具”，不是完整的 Xcode 应用（Xcode 有十几 GB 大，我们不需要）。命令行工具只有约 740 MB。

怎么安装

1. 打开终端（如果还没打开，按 Command+空格 搜索 Terminal）
2. 在终端里输入以下命令，然后按回车：

xcode-select --install

3. 电脑会弹出一个对话框，询问是否安装命令行工具
4. 点击 “安装”（不要点“获取 Xcode”，那是另一个很大的软件）
5. 继续点击“同意”接受许可协议
6. 等待下载和安装完成，大约需要 5-20 分钟（取决于网速）
7. 看到“软件已安装”的提示后，点击“完成”

验证安装成功

安装完成后，在终端输入：

git --version

如果看到类似这样的输出，就成功了：

git version 2.39.3 (Apple Git-146)

遇到问题：如果提示“已经安装了命令行工具”，那说明你的电脑之前装过，直接跳到下一步。

第 3 步：安装 Homebrew

为什么需要它

Homebrew 是 macOS 上的“应用商店”，但它在终端里使用。

用 Homebrew，你只需要一行命令就能安装软件，不用去各种官网搜索下载，也不用担心安装路径之类的问题。

装完 Homebrew 之后，你会发现：后面的 Git、Node.js、Opencode、VS Code、Miniconda、Pandoc，全部一行命令搞定。 这就是 Mac 安装的核心优势。

怎么安装

打开终端（按 Command+空格 搜索 Terminal），复制并粘贴以下整段命令，然后按回车：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

系统会要求你输入电脑密码。注意：输密码时屏幕不会显示任何字符，不会出现星号也不会出现小黑点，看起来像是没有反应——这是正常的安全设计，不是卡住了。放心输入完密码，按回车就行。

==> Checking for `sudo` access (which may request your password)...
Password:

网络提示：这个命令需要访问 GitHub。如果你的网络访问 GitHub 较慢或失败，可以改用清华大学镜像安装。在终端依次运行以下命令：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
git clone --depth=1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git brew-install
/bin/bash brew-install/install.sh
rm -rf brew-install

详细说明参见：清华大学 Homebrew 镜像帮助

安装过程中可能询问是否继续安装，按回车确认即可。整个过程大约 5-15 分钟。

Apple Silicon（M 系列芯片）用户额外步骤

如果你的 Mac 是 M1、M2、M3 或 M4 芯片（2020 年以后买的 Mac 大多是），安装完成后需要多做一步。

安装结束时，终端会显示类似这样的提示：

==> Next steps:
Add Homebrew to your PATH in /Users/你的用户名/.zprofile

按照提示，在终端输入（复制粘贴这两行，分两次按回车）：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile

如何判断你的芯片类型：点击屏幕左上角苹果图标 → “关于本机”，查看“芯片”一栏。写着“Apple M1/M2/M3/M4”就是 Apple Silicon；写着“Intel”就是 Intel 芯片。

验证安装成功

在终端输入：

brew doctor

如果看到 Your system is ready to brew.，说明安装成功。

再输入：

brew --version

看到类似 Homebrew 4.x.x 的版本号，确认安装正常。

配置清华镜像加速（推荐）

Homebrew 默认从国外服务器下载软件，速度可能较慢。配置清华大学镜像后，后续所有 brew install 都会走国内源，速度快很多。

在终端依次执行以下命令（复制粘贴即可）：

echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"' >> ~/.zprofile
echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"' >> ~/.zprofile
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zprofile
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zprofile
source ~/.zprofile

这几行命令只需要执行一次，以后每次打开终端都会自动生效。

第 4 步：一键安装所有工具

Homebrew 就位，接下来两行命令把剩下六个工具全装上。

打开终端，复制粘贴以下两行命令，按回车执行：

brew install git node pandoc anomalyco/tap/opencode
brew install --cask visual-studio-code miniconda

第一行安装命令行工具（Git、Node.js、Pandoc、Opencode），第二行安装图形界面应用（VS Code、Miniconda）。

整个过程大约 10-20 分钟，取决于网速。可以去倒杯水，回来差不多就好了。

验证安装成功

安装完成后，在终端逐条输入以下命令，每条都应该显示版本号：

git --version
node --version
npm --version
opencode --version
code --version
pandoc --version

六条命令都显示了版本号？恭喜，软件全部安装完成。

注意：conda 命令现在还用不了，需要下一步初始化之后才行，这是正常的。

遇到问题：如果某个命令提示“找不到”，关掉终端窗口，重新打开一个，再试一次。

第 5 步：必要配置

软件装好了，还有两个工具需要做一点配置才能正常使用。

配置 Git 身份

Git 需要知道你是谁，才能在记录里标注是谁做的修改。执行以下两条命令（把引号里的内容替换成你自己的信息）：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱地址"

例如：

git config --global user.name "张三"
git config --global user.email "zhangsan@example.com"

这两条命令只需要执行一次，以后不用再配置。

验证配置：

git config --global --list

看到你刚才填写的名字和邮箱，配置就完成了。

初始化 Miniconda

Miniconda 安装后需要初始化一次，让终端识别 conda 和 python 命令。

在终端输入：

conda init zsh

执行后，关闭终端，重新打开一个新的终端窗口。这一步必须做，新配置要在新窗口才能生效。

打开新终端后，你会注意到提示符前面多了一个 (base) 字样，这表示 conda 的默认环境已经自动激活，Python 已经可以使用了。

验证一下：

conda --version
python --version

看到 conda 版本号和 Python 3.12.x（或更高），说明一切就绪。

macOS 安装完成！

至此，Mac 上需要单独安装的软件已经全部就绪。接下来请跳到 第三部分：通用配置，完成 Skills 扩展包安装和 API 密钥配置。

打开终端，逐条输入以下命令，每条都应该显示版本号：

git --version
node --version
npm --version
opencode --version
code --version
conda --version
pandoc --version

装好的工具都是什么

不关心细节的读者可以直接跳到下一节。想了解每个工具是干嘛的，往下看。

Git — 版本控制工具。它帮你记录文件的每次修改，出了问题可以随时回到之前的状态。Opencode 在工作时会用 Git 管理文件变更，AI 改了什么、改错了想回退，全靠它。

Node.js — JavaScript 运行环境。Opencode 是用 JavaScript 开发的，需要 Node.js 才能跑起来。安装 Node.js 时会同时装上 npm（包管理器），后续安装扩展可能用到。

Opencode — 整个工作套装的核心，一个在终端里运行的 AI 助手。它能读写文件、执行命令、联网查询，用自然语言就能控制。和网页版 AI 聊天不同，Opencode 直接在你的电脑上工作，可以处理本地文件。

VS Code — 目前最流行的代码和文本编辑器。配合 Opencode 使用，可以在同一个窗口里查看文件和跟 AI 对话。VS Code 插件安装请到第四部分统一完成，Mac 和 Windows 操作完全一样。

Miniconda — Python 环境管理工具。安装它之后，你可以随时创建 Python 工作环境，用于数据分析、自动化脚本等任务。比完整版 Anaconda 小很多，但功能够用。

Pandoc — 文档格式转换工具，能把 Markdown 文件转成 Word、PDF 等格式。配合 Opencode 的 Skills 扩展包，可以一键把 AI 生成的内容转成 Word 文档。

macOS 常见问题解答

Q：安装过程中提示“无法打开，因为无法验证开发者”

这是 macOS 的安全提示。解决方法：

1. 打开“系统设置” → “隐私与安全性”
2. 在“安全性”部分，点击“仍要打开”

Q：Homebrew 安装很慢或连接超时

说明访问 GitHub 受到了限制。改用清华大学镜像安装，参见第 3 步的“网络提示”部分，或访问：清华大学 Homebrew 镜像帮助

Q：安装软件时总是要输入密码

这是正常的。macOS 需要你确认“我知道在安装软件”。输入你登录电脑的密码，输入时屏幕不显示任何字符，这是安全设计，不是出错了。

Q：某个命令输入后提示“command not found”

通常是终端需要刷新。关掉当前终端窗口，重新打开一个，再输入命令。

Q：Opencode 里 AI 回复很慢

智谱 AI 的免费模型（GLM-5 Free）性能有限，高峰期可能较慢。如果需要更快的响应，考虑升级到 Coding Plan。

Q：忘记保存 API 密钥了

不要担心。登录智谱 AI 开放平台，进入“API 密钥管理”，可以重新创建一个新密钥（旧密钥无法找回，新建一个替代即可）。

第二部分：Windows 用户

写在前面

这份教程会手把手带你完成 Opencode AI 工作套装的全套安装。不需要任何编程基础，只需要按步骤操作就行。

整个过程分 9 步，每步都会告诉你：

• 这个工具是什么、为什么要装
• 怎么下载、怎么安装
• 装完怎么验证成功

遇到可能出错的地方，教程会提前提醒你。遇到报错不要慌，先看本步骤的故障排查提示。

第一步：认识 PowerShell

什么是 PowerShell

PowerShell 是 Windows 内置的“命令窗口”。你在这里输入文字命令，电脑就会执行对应的操作。

它看起来像一个黑色或蓝色的窗口，显示一行提示符，等你输入命令。别被它的样子吓到——它只是一个接受文字指令的地方，就像微信输入框，只不过对象是电脑系统。

怎么打开 PowerShell

方法一：开始菜单搜索（最简单，Windows 10 和 11 都能用）

1. 点击屏幕左下角的 Windows 图标（或按键盘上的 Windows 键）
2. 直接用键盘输入 PowerShell
3. 搜索结果里会出现 “Windows PowerShell”
4. 点击它，打开

打开后，你会看到一个窗口，里面有这样一行文字：

PS C:\Users\你的用户名>

这就是“提示符”。PS 表示 PowerShell，C:\Users\你的用户名 是你当前所在的文件夹，> 后面是光标，等待你输入命令。

方法二：右键开始按钮（更快捷）

1. 用鼠标右键点击左下角的 Windows 图标
2. 弹出一个菜单
3. Windows 11 上点击 “Windows 终端”；Windows 10 上点击 “Windows PowerShell”
4. 窗口弹出，你就进入了

提示：Windows 10 和 Windows 11 的区别

• Windows 11 已经预装了“Windows 终端”（界面更现代，有标签页功能）
• Windows 10 默认只有老式的 PowerShell 窗口，但功能完全一样

无论哪种，操作方式都相同：在提示符后输入命令，按 Enter 执行。

PowerShell 基本操作

在正式安装前，先了解几个基本操作：

关于粘贴的说明：

• Windows 10 的 PowerShell 不支持 Ctrl+V 粘贴，需要右键点击窗口空白处来粘贴
• Windows 11 的新版 Windows 终端已经支持 Ctrl+V 直接粘贴

第二步：设置 PowerShell 权限

为什么要做这一步

Windows 为了安全，默认禁止运行从外部下载的脚本程序（.ps1 文件）。问题是，我们接下来要安装的很多工具（比如 npm、opencode）在安装后都会生成这类脚本文件。如果不改这个设置，你运行这些工具时会收到错误：

xxx : 无法加载文件，因为在此系统上禁止运行脚本。

这就像你的电脑设置了“只认识家里的东西，外来的一律不允许运行”。我们要把这个规则改成“外来的东西需要经过认证才能运行，本地生成的东西自由运行”，这样就安全又实用。

怎么操作

1. 打开 PowerShell（用第一步的方法，普通用户权限就行，不需要管理员）
2. 在提示符后面输入这条命令，然后按 Enter：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

3. 如果系统弹出提示问你“是否要更改执行策略？”，输入 Y，然后按 Enter 确认
4. 验证设置成功：输入以下命令，按 Enter：

Get-ExecutionPolicy

如果返回 RemoteSigned，说明设置成功了。

这条命令是什么意思

• Set-ExecutionPolicy = 设置执行策略
• RemoteSigned = 本地脚本自由运行；从网上下载的脚本需要有数字签名（即需要经过认证）
• -Scope CurrentUser = 只对你这个用户账户生效，不影响其他用户，也不需要管理员权限

第三步：安装 Git

什么是 Git，为什么需要它

Git 是一个“版本控制”工具。简单说，它帮你记录文件的每次修改，随时可以撤销、恢复到之前的版本。

你可以把它想象成文档的“自动存档”功能，但功能更强大：每次存档都有记录，可以跨越时间点查看任意一次的文件状态。

Opencode 依赖 Git 来追踪 AI 对文件的修改。当 AI 修改了某个文件，Git 会把改动记录下来，你可以随时查看或撤销。这是 AI 辅助工作的安全保障。

下载安装包

1. 打开浏览器，访问 Git 官网下载页：https://git-scm.com/downloads/win

这个页面会直接显示 Windows 版本的下载选项，点击相应链接开始下载。

2. 浏览器会开始下载一个 .exe 文件（文件名类似 Git-2.53.0-64-bit.exe，文件大小约 60MB）

安装步骤

1. 双击下载好的 .exe 文件，启动安装向导

2. 出现用户账户控制弹窗时，点击 “是” 允许安装

3. 安装过程中，大部分选项保持默认即可，只有 一步特别重要：

   当出现 “Adjusting your PATH environment”（调整系统 PATH）的页面时，确保选择的是：

   “Git from the command line and also from 3rd-party software”（第二个选项）

   这一步决定你能否在 PowerShell 中直接使用 git 命令。如果选错了，后续 Opencode 找不到 Git，会报错。

4. 其余选项全部保持默认，一路点 “Next”，最后点 “Install”

5. 安装完成后点 “Finish”

验证安装成功

安装后，关闭当前的 PowerShell 窗口，重新打开一个新的（这一步很重要，系统需要重新加载 PATH 设置）。

然后输入：

git --version

按 Enter 后，如果看到类似这样的输出：

git version 2.53.0.windows.1

说明 Git 安装成功了。

常见问题：提示“不是内部或外部命令”

如果看到 'git' 不是内部或外部命令 这类错误：

1. 先确认是否重新打开了 PowerShell（不是刷新，是关掉重开）
2. 如果还是不行，可能是安装时 PATH 选项没有选对，重新运行安装程序，在 PATH 那步选择第二个选项

第四步：配置 Git

为什么要配置

Git 需要知道“这次修改是谁做的”。就像签名一样，每次提交记录都会带上你的名字和邮箱。

这是一次性设置，设好了就不用再管。

配置命令

打开 PowerShell，输入以下两条命令（把引号里的内容换成你自己的）：

git config --global user.name "你的名字"

按 Enter 执行，然后输入第二条：

git config --global user.email "你的邮箱@example.com"

按 Enter 执行。

这两条命令执行后不会有任何输出，这是正常的——没有报错就是成功。

验证配置

输入以下命令查看配置是否保存成功：

git config --global --list

你会看到类似：

user.name=你的名字
user.email=你的邮箱

这样就配置好了。

小提示：名字和邮箱可以用中文或英文，没有严格要求。建议用常用邮箱，以后连接 GitHub 会用到。

第五步：安装 Node.js

什么是 Node.js，为什么需要它

Node.js 是一个 JavaScript 运行环境。你可以把它理解为一个“平台”，就像 Python 是运行 Python 程序的平台，Node.js 是运行 JavaScript 程序的平台。

Node.js 附带了一个叫 npm 的工具（Node Package Manager，软件包管理器）。npm 就像一个“软件商店”，你可以用一行命令安装成千上万的工具，包括接下来要安装的 Opencode。

下载安装包

1. 打开浏览器，访问 Node.js 官网下载页：https://nodejs.org/en/download

3. 选择 LTS 版本（Long Term Support，长期支持版，更稳定），下载 Windows Installer (.msi) 格式

   文件名类似 node-v22.x.x-x64.msi，大小约 30MB

安装步骤

1. 双击下载好的 .msi 文件，启动安装向导
2. 点击 “Next” 进入下一步
3. 阅读并接受许可协议，勾选 “I accept the terms in the License Agreement”，点击 “Next”
4. 安装路径保持默认（C:\Program Files\nodejs\），点击 “Next”
5. 出现功能选择页面，保持默认，确保 “Add to PATH” 这一项是选中的（默认就是选中的）
6. 点击 “Next”，然后点击 “Install”
7. 弹出用户账户控制窗口，点击 “是”，开始安装
8. 安装完成后，点击 “Finish”

验证安装成功

关闭当前 PowerShell，重新打开一个新窗口，然后输入：

node --version

应该看到类似 v22.x.x 的输出。

再输入：

npm --version

应该看到类似 10.x.x 的输出。

两个命令都返回了版本号，说明 Node.js 安装成功。版本号以实际显示为准，不需要和上面完全一致。

常见问题：命令未找到

如果提示找不到命令：

1. 关闭 PowerShell，重新打开一个新窗口再试
2. 如果还是不行，重新运行安装包，确认 “Add to PATH” 那步是选中的

第六步：安装 Opencode

安装命令

确保 Node.js 已经安装好，然后打开 PowerShell，输入：

npm install -g opencode-ai

这条命令的意思是：用 npm 工具，全局安装（-g 表示 global）一个叫 opencode-ai 的软件包。

安装过程需要从网络下载文件，根据网速可能需要 1-5 分钟。你会看到一些滚动的文字，这是正常的进度信息。

等待安装完成，出现命令提示符（>）表示安装结束。

验证安装成功

输入以下命令：

opencode --version

如果看到版本号输出（版本号以实际显示为准），说明安装成功。

常见问题：PowerShell 报错“无法加载文件”

如果看到这类错误：

opencode : 无法加载文件 C:\Users\...\opencode.ps1，因为在此系统上禁止运行脚本。

这是因为第二步的执行策略没有生效。解决方法：

回到第二步，重新执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

然后关闭 PowerShell，重新打开，再输入 opencode --version。

常见问题：npm 安装超时或失败

如果提示网络超时，可以加上官方源参数重试：

npm install -g opencode-ai --registry=https://registry.npmjs.org

第七步：安装 VS Code

什么是 VS Code，为什么需要它

VS Code（Visual Studio Code）是微软出品的免费代码编辑器。它可以打开和编辑各种文本文件（Markdown、Python、JSON 等），界面清晰，操作直观。

在 AI 工作流中，VS Code 用来：

• 查看和编辑 Opencode 生成的文件
• 预览 Markdown 文档
• 管理项目文件夹

下载安装包

1. 打开浏览器，访问 VS Code 官网：https://code.visualstudio.com

2. 点击蓝色的 “Download for Windows” 按钮
3. 浏览器会下载一个 .exe 文件（文件名类似 VSCodeUserSetup-x64-1.109.4.exe，大小约 100MB）

安装步骤

1. 双击下载的 .exe 文件

2. 接受许可协议，点击 “我同意”

3. 安装位置保持默认，点击 “下一步”

4. 在“选择附加任务”页面，建议勾选以下选项（方便以后使用）：

   • “将'通过 Code 打开'操作添加到 Windows 资源管理器文件上下文菜单”
   • “将'通过 Code 打开'操作添加到 Windows 资源管理器目录上下文菜单”
   • “将 Code 注册为受支持的文件类型的编辑器”
   • “添加到 PATH”（这项一定要勾选！）

5. 点击 “下一步”，然后 “安装”

6. 安装完成后，点击 “完成”，VS Code 会自动启动

验证安装成功

在 PowerShell 输入 code --version，看到版本号说明安装成功。也可以在开始菜单搜索 VS Code，正常启动即可。

VS Code 插件安装请到第四部分统一完成，Mac 和 Windows 操作完全一样。

第八步：安装 Miniconda

什么是 Miniconda，为什么需要它

Miniconda 是一个 Python 环境管理工具。Python 是做数据分析最常用的编程语言，Miniconda 让你方便地安装 Python 和各种分析工具包。

安装 Miniconda 后，你就有了 Python，以后可以用 Opencode 指挥 AI 写 Python 代码，处理 Excel 数据、绘制图表、做统计分析。

下载安装包

1. 打开浏览器，访问 Miniconda 下载页：https://docs.anaconda.com/miniconda/

2. 找到 Windows 那一栏，下载 “Miniconda3 Windows 64-bit”

   文件名是 Miniconda3-latest-Windows-x86_64.exe，大小约 70MB

安装步骤

1. 双击下载的 .exe 文件，启动安装向导

2. 点击 “Next”

3. 接受许可协议，点击 “I Agree”

4. 安装类型选择 “Just Me”（推荐，不需要管理员权限），点击 “Next”

5. 安装路径保持默认（通常是 C:\Users\你的用户名\miniconda3），点击 “Next”

6. 在 Advanced Options 页面，有两个选项：

   • 第一个选项 “Add Miniconda3 to my PATH environment variable”：建议保持默认（不勾选）

     Anaconda 官方明确不推荐勾选此项（安装界面上也标注了“Not recommended”），因为它会影响系统 PATH，可能与其他 Python 工具冲突。不用担心——安装完成后，我们用一条命令来初始化，效果完全一样。

   • 第二个选项 “Register Miniconda3 as my default Python”：可以勾选

7. 点击 “Install”，等待安装完成（约 2-3 分钟）

8. 安装完成后点击 “Finish”

初始化 conda

安装完成后，需要执行一步初始化，让 PowerShell 能识别 conda 和 python 命令。

打开 PowerShell（普通权限即可），输入：

conda init powershell

执行后，你会看到一些文字提示说明初始化完成。

关闭当前 PowerShell，重新打开一个新窗口。 这一步必须做，新配置要在新窗口里才能生效。

验证安装成功

重新打开 PowerShell 后，你会注意到提示符前面多了 (base) 字样：

(base) PS C:\Users\你的用户名>

这表示 conda 的默认环境已经自动激活，Python 已经可以使用了。

验证一下：

conda --version
python --version

应该分别看到 conda 和 Python 的版本号（Python 应为 3.12 或更高）。

常见问题：conda 命令未找到

如果提示 conda 不是可识别的命令：

1. 先确认是否执行了 conda init powershell 这步
2. 确认是否关闭了 PowerShell 并重新打开
3. 如果还是不行，打开开始菜单，搜索 “Anaconda Prompt (miniconda3)”，用这个专用终端来运行 conda 命令，效果完全一样

第九步：安装 Pandoc

什么是 Pandoc，为什么需要它

Pandoc 是一个文档格式转换工具。它可以把 Markdown 文件转换为 Word 文档、PDF、HTML 等各种格式。

在 AI 工作流中，AI 通常生成 Markdown 格式的文档，用 Pandoc 可以一键把 Markdown 转成 Word 或 PDF，方便提交作业或报告。

下载安装包

1. 打开浏览器，访问 Pandoc 安装页：https://pandoc.org/installing.html

2. 找到 Windows 部分，点击下载链接
3. 你会跳转到 GitHub，找到并下载 .msi 文件（文件名类似 pandoc-3.6.2-windows-x86_64.msi，大小约 30MB）

安装步骤

1. 双击下载的 .msi 文件
2. 出现安装向导，点击 “Next”
3. 接受许可协议，点击 “Next”
4. 安装路径保持默认，点击 “Next”
5. 点击 “Install”，弹出用户账户控制窗口点击 “是”
6. 安装完成，点击 “Finish”

Pandoc 会自动添加到系统 PATH，安装后即可在 PowerShell 中使用。

验证安装成功

关闭并重新打开 PowerShell，输入：

pandoc --version

看到版本号输出，说明安装成功。

Windows 安装完成！

至此，Windows 上需要单独安装的软件已经全部就绪。接下来请跳到 第三部分：通用配置，完成 Skills 扩展包安装和 API 密钥配置。

打开 PowerShell，依次执行以下命令，每条都应该返回版本号：

git --version
git config --global user.name
node --version
npm --version
opencode --version
code --version
conda --version
pandoc --version

Windows 日常使用快速参考

每次使用 Opencode 时：打开 PowerShell → 进入工作目录（cd $env:USERPROFILE\opencode-lab）→ 输入 opencode 启动。

Opencode 的详细操作指南（常用命令、快捷键、工作模式等）请参见第四部分“Opencode 操作完整指南”。

遇到问题怎么办

通用排查步骤：

1. 关闭 PowerShell，重新打开一个新窗口，再试一次
2. 确认命令拼写是否正确（注意大小写）
3. 查看本教程对应步骤的“常见问题”说明
4. 访问 Opencode 官方文档：learnopencode.com

遇到网络问题：

• 有些软件需要访问 GitHub，如果下载很慢，可以多等一会
• 如果长时间没有反应，按 Ctrl + C 取消，稍后重试

遇到权限问题：

• 大多数情况用普通 PowerShell 就够了
• 如果提示需要管理员权限：右键 PowerShell → “以管理员身份运行”

第三部分：通用配置（Mac / Windows 相同）

以下两步操作在 Mac 和 Windows 上完全一样，两个系统的用户都读这一部分就行。

安装 Skills 扩展包

前面你一直在“给 Opencode 搭舞台”。现在，终于到了让它上台表演的时刻！

这一步，你要亲眼见证 Opencode 的能力——你只需要粘贴一段话，它就能自动从 GitHub 下载文件、创建目录、安装扩展，全程不用你动手。

这个扩展包有什么

Skills 扩展包（GitHub 仓库）包含 15 个实用技能：

让 Opencode 自己动手

第一步：创建工作目录并启动 Opencode

打开终端（Mac）或 PowerShell（Windows），输入以下命令：

• Mac 用户：

mkdir ~/opencode-lab
cd ~/opencode-lab
opencode

• Windows 用户：

mkdir $env:USERPROFILE\opencode-lab
cd $env:USERPROFILE\opencode-lab
opencode

Opencode 会启动，显示一个文字界面（TUI）。

第二步：选择免费模型

Opencode 开箱自带多个免费 AI 模型，不需要注册任何账号就能直接使用。

在 Opencode 的输入框里输入：

/models

按回车后，会弹出模型选择列表。

在列表中找到标注了 Free 的模型（如 GLM-5 Free、Big Pickle、MiniMax M2.5 Free 等），用方向键选中，按回车确认。

第三步：测试模型连接

选好模型后，输入一句话测试：

你好，请简单介绍一下你自己

如果 AI 正常回复，说明模型连接成功，可以继续下一步了。

第四步：让 Opencode 安装扩展包

把下面这段话完整粘贴到 Opencode 输入框，按回车：

请帮我从 GitHub 下载并安装 Skills 扩展包。步骤如下：
1. 克隆仓库 https://github.com/Xueheng-Li/ai-tools-installation.git 到临时目录
2. 将仓库中 recommended_skills 文件夹下的所有子文件夹复制到 ~/.config/opencode/skills/
3. 完成后删除临时目录

然后坐下来看它表演。Opencode 会自动执行每一步：克隆仓库、创建目录、复制文件、清理临时文件。整个过程大约 1-3 分钟。

这就是 Opencode 的工作方式——你用自然语言描述任务，它来执行。以后处理文件、写代码、做分析，都是这个套路。

第五步：验证安装

在 Opencode 里输入：

/skills

如果列表中显示了 15 个技能，说明安装成功！

按 Ctrl+D 退出 Opencode。

配置 API 密钥（推荐）

前面用的免费模型能力有限，适合体验和简单任务。如果你想用更强大的 AI 模型，需要配置自己的 API 密钥。

我推荐在以下几个国内厂商里选一家，它们最近两个月发布的新模型都很不错

• 智谱 AI: https://www.bigmodel.cn/glm-coding
• Kimi: https://www.kimi.com/code/
• MiniMax: https://platform.minimaxi.com/

下面我们以智谱 AI 为例。

注册智谱 AI

1. 打开浏览器，访问：https://www.bigmodel.cn/glm-coding
2. 点击右上角“注册/登录”
3. 用手机号 + 短信验证码注册（无需实名认证）
4. 注册完成后自动进入控制台

获取 API 密钥

1. 登录后，点击左侧菜单的 “API 密钥管理”

   或直接访问：API 密钥管理页面

2. 点击“创建 API 密钥”按钮

3. 输入一个密钥名称（随便取，方便自己识别）

4. 系统生成一串以密钥

5. 立即复制并保存这个密钥——它只显示一次，关闭后就看不到完整内容了！

安全提醒：API 密钥相当于你账户的密码。不要把它发给别人，不要上传到 GitHub，不要截图分享。

智谱 AI Coding Plan

如果你打算重度使用 Opencode，可以考虑订阅智谱 AI 的 Coding Plan。这个套餐专为 AI 编程助手设计，用量更大。

Coding Plan 网址：https://www.bigmodel.cn/glm-coding

套餐有三档： Lite（适合轻度使用），Pro（适合重度使用），Max（适合专业开发）。可以按自己的需求选择。

在 Opencode 中连接 API

启动 Opencode（进入之前创建的 opencode-lab 目录后输入 opencode），然后：

第一步：连接 AI 提供商

在输入框里输入：

/connect

按回车后，界面会显示提供商列表。

如果你有 Coding Plan 订阅：选择 Zhipu AI Coding Plan，输入你的 API 密钥。

如果你使用免费模式：选择 Zhipu AI（普通 API），输入你的 API 密钥。

第二步：选择模型

连接成功后，输入：

/models

选择你想用的模型。推荐 GLM-5。

第三步：测试连接

输入一句话测试：

你好，请简单介绍一下你自己

如果 AI 正常回复，说明配置成功！

按 Ctrl+D 退出 Opencode。

全部完成！下一步

安装配置全部完成后，你可以：

1. 开始使用 Opencode：在任意文件夹里输入 opencode 启动，用中文和 AI 对话

2. 了解更多命令：在 Opencode 里按 Ctrl+P 查看所有可用命令

3. 切换 AI 模式：

   • 按 Tab 键切换 Build（执行）/ Plan（规划）两种模式
   • Build 模式：AI 可以修改文件
   • Plan 模式：AI 只分析，不改动任何文件

4. 管理会话：

   • 输入 /new 开始新对话
   • 输入 /compact 压缩长对话节省空间
   • 输入 /models 切换不同 AI 模型

Opencode 官方资源：

• 官方网站：opencode.ai
• 中文文档：opencode.ai/zh
• 学习网站：learnopencode.com

想了解如何在 VS Code 中配合使用 Opencode？请继续阅读第四部分。

第四部分：在 VS Code 中使用 Opencode

写在前面

前面三部分，你已经把所有工具都装好了。接下来这一步，是把两个最重要的工具——VS Code 和 Opencode——连起来用。

为什么要在 VS Code 里用 Opencode？

你完全可以单独打开终端来运行 Opencode。但这样做有个麻烦：你得在两个窗口之间来回切换——左边是终端窗口跑 Opencode，右边是文件管理器看文件。就像同时翻两本书，一本放桌子左边一本放右边，看一句翻一下，很容易乱。

VS Code 把这两件事合到了一起。上半部分看文件、改文件，下半部分跟 Opencode 对话。一个窗口搞定所有事情，效率高很多。

下图是 Opencode 在终端里实际运行的样子——上面是 AI 的对话和操作记录，下面是输入框：

接下来，我们一步步来：先认识 VS Code 界面，再打开终端，启动 Opencode，最后学几个常用操作。

认识 VS Code 界面

第一次打开 VS Code，你可能会觉得界面有点复杂。别担心，你只需要认识五个区域就够了。

主要区域

日常使用中，你最常打交道的就是三个地方：侧边栏（看文件）、编辑区（改文件）、面板区（跑 Opencode）。

安装扩展插件

VS Code 的强大之处在于它有海量的扩展插件。活动栏（区域 A）最下面那个由四个小方块组成的图标，就是 扩展（Extensions） 按钮。

点击它（或按 Cmd+Shift+X / Ctrl+Shift+X），左侧会打开扩展面板。在搜索框里输入插件名称，找到后点击蓝色的 Install 按钮就装好了。

下面是我们推荐安装的 3 个插件，能大幅提升使用体验。依次搜索并安装：

插件 1：Office Viewer（Markdown 阅读器）

• 搜索：cweijan.vscode-office
• 功能：在 VS Code 里直接预览 Markdown、Word 等文件

插件 2：Git Graph（Git 可视化）

• 搜索：mhutchie.git-graph
• 功能：用图形方式查看 Git 提交历史

插件 3：Marp（幻灯片制作）

• 搜索：marp-team.marp-vscode
• 功能：把 Markdown 文件转成精美的幻灯片

每个插件在搜索结果里找到后，点击“安装”（Install）按钮即可。

把界面切换成中文

VS Code 默认是英文界面。如果你更习惯中文，可以一键切换：

1. 按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows）打开命令面板
2. 输入 confi lan，在下拉列表中选择 Configure Display Language

3. 在弹出的语言列表中选择 中文(简体) (zh-cn)

4. VS Code 会提示需要重启，点击 Restart 即可

重启后，菜单和界面就全变成中文了。

切换主题颜色

VS Code 默认是深色主题，如果你想换成浅色或其他配色方案：

1. 按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows）打开命令面板
2. 输入 color theme，选择 Preferences: Color Theme

3. 用上下方向键浏览不同主题，实时预览效果，按 Enter 确认选择

常用的内置主题有 Light+（浅色）、Dark+（深色）、Monokai 等，选一个你看着舒服的就好。

打开工作文件夹

什么是“工作文件夹”

Opencode 启动后，它只能看到当前文件夹里的文件。你在哪个文件夹里启动它，它就在哪个文件夹里工作。

所以，在启动 Opencode 之前，你得先告诉 VS Code：我要在这个文件夹里干活。这个文件夹就叫工作文件夹。

比如你有一篇论文的资料放在桌面的 my-paper 文件夹里，你就把这个文件夹作为工作文件夹打开。之后 Opencode 就能读到里面所有的文件。

三种打开方式

方式一：菜单打开（最直观）

Mac 用户注意：Mac 上没有“Open Folder”选项，用“Open...”就行，选中文件夹后点“打开”即可。

方式二：拖拽打开（最省事）

直接把文件夹从 Finder（Mac）或资源管理器（Windows）拖到 VS Code 窗口上，松手就行。

方式三：命令行打开（最快）

如果你已经在终端里了，一行命令就能打开：

code /path/to/your/folder

比如打开桌面上的 my-paper 文件夹：

# Mac
code ~/Desktop/my-paper

# Windows（PowerShell）
code $env:USERPROFILE\Desktop\my-paper

Mac 用户注意：首次使用 code 命令前，需要先在 VS Code 中安装这个命令。打开 VS Code，按 Cmd+Shift+P 打开命令面板，搜索 Shell Command: Install ‘code’ command in PATH，点击执行。之后就可以在终端里用 code 命令了。

打开后，左边侧边栏会显示这个文件夹里的所有文件和子文件夹。你一眼就能看到全部内容：

打开 VS Code 内置终端

为什么用 VS Code 内置终端

前面说了，一个窗口搞定所有事情。上面看文件，下面跑 Opencode，不用来回切窗口。VS Code 的内置终端和你电脑上独立打开的终端功能完全一样，该怎么用还怎么用。

怎么打开

有三种方法，选一个你顺手的。

方法一：点击图标（最简单，推荐新手用）

看 VS Code 窗口的右上角，有一排小图标。找到下图中高亮的那个（Toggle Panel），点一下，终端面板就出来了。再点一下，终端就收起来。

方法二：快捷键（熟练后更快）

` 这个键在哪？它在键盘左上角，数字 1 的左边，Esc 键的下面。和波浪号 ~ 是同一个键。

Mac 用户特别注意：这里用的是 Control 键，不是 Command（⌘）键。这和 Mac 上大多数快捷键的习惯不一样，刚开始可能会按错，多试几次就记住了。

方法三：菜单打开

点击菜单栏 Terminal > New Terminal。

打开后，窗口底部会出现一个面板，里面就是终端。你会看到熟悉的提示符：

Mac 上大概长这样：

username@MacBook-Pro folder-name %

Windows 上大概长这样：

PS C:\Users\YourName\folder-name>

终端基本操作

VS Code 内置终端和你之前用过的独立终端完全一样。所有命令都能用，不需要学新东西。

有几个小技巧可以让你用起来更舒服：

在 VS Code 终端中启动 Opencode

终端打开了，接下来就可以启动 Opencode 了。

启动步骤

第一步：确认你在正确的文件夹里

在终端中输入：

pwd

（Windows PowerShell 也支持 pwd 命令。）

它会显示当前所在的文件夹路径。如果 VS Code 已经打开了你的工作文件夹，这里显示的就是那个文件夹的路径。确认一下是你想要的位置。

第二步：启动 Opencode

输入：

opencode

按回车。

第三步：看到 TUI 界面

几秒钟后，终端里会出现 Opencode 的交互界面（TUI）。屏幕上方是对话区域，下方有一个输入框，等你输入问题。

到这一步，你就可以在 VS Code 里直接和 Opencode 对话了。上面看文件，下面跟 AI 聊天，一个窗口搞定。

试着输入一句话（比如“你好”），看看 AI 是否正常回复：

Opencode 操作完整指南

如果你只想快速查看常用操作，第二部分末尾的“日常使用快速参考”已经列出了最常用的命令。这里提供更完整的操作指南。

常用命令

在 Opencode 输入框里输入 / 加命令名，按回车执行。输入 / 后会弹出命令自动补全列表：

输入 /models 后弹出模型选择对话框，可以搜索和切换不同的 AI 模型：

输入 /new 可以新建对话：

输入 /themes 可以切换界面主题，选一个你喜欢的配色：

快捷键

Opencode 有一套自己的快捷键。最常用的几个记住就行，其他的用到再查。

核心快捷键（必记）：

按 Ctrl+P 后弹出的命令面板长这样，列出了所有可用操作和对应的快捷键：

对话管理快捷键：

Opencode 的很多快捷键采用两步操作：先按 Ctrl+X（这是一个起手式），松手，再按第二个键。就像手机先解锁才能操作一样，先按 Ctrl+X 激活快捷键模式，再按对应的字母。

输入框快捷键：

两种工作模式

按 Tab 键可以在两种模式之间切换。输入框左下角会显示当前是哪个模式。

Build 模式（默认）：读文件、写文件、改文件、执行命令，什么都能做。让 AI 实际动手干活时用这个。

Plan 模式：只能读文件和分析，不能修改任何东西。让 AI 先想方案、列计划，但不要动手改时用这个。

按 Tab 切换到 Plan 模式后，输入框左下角会从“Build”变成“Plan”：

你也可以通过 Tab 键弹出的代理选择界面来切换：

推荐的工作流程：先切到 Plan 模式，让 AI 分析情况、制定方案。你觉得方案没问题了，再切回 Build 模式，让它动手执行。这样更安全，不容易改错文件。

实用技巧

这几个小技巧日常很常用，知道了能省不少事。

引用文件：用 @

在输入框里输入 @，后面跟文件名，Opencode 会把这个文件的内容加入对话。支持模糊搜索，不用输完整文件名。

@report.md 帮我把这篇文章的摘要翻译成英文

@论文初稿.docx 帮我检查这篇文章有没有语法错误

执行命令：用 !

以 ! 开头输入命令，Opencode 会先执行这个命令，然后把输出结果加入对话。

!ls -la
!git log --oneline -5

拖入图片

把图片直接拖到终端窗口中，Opencode 会识别图片内容，你可以针对图片提问。

打断 AI

AI 正在回答，你觉得方向不对，随时按 Escape 键打断它，然后重新说你的需求。

退出后想再用怎么办

不小心退出了 Opencode，或者关掉了 VS Code？没关系，重新打开 VS Code → 打开工作文件夹 → 打开终端（Ctrl+`）→ 输入 opencode 回车，就回来了。之前的对话记录还在，输入 /sessions 就能找到。

附录：安装完成检查清单

完成所有安装步骤后，用这份清单逐项确认。所有项目都打勾，说明你的 Opencode AI 工作套装已经完整配置好了。

基础工具

✅ Git 已安装 — 验证：git --version，显示版本号 ✅ Git 用户名已配置 — 验证：git config --global user.name，显示你的名字 ✅ Git 邮箱已配置 — 验证：git config --global user.email，显示你的邮箱 ✅ Node.js 已安装 — 验证：node --version，显示 v22.x.x ✅ npm 已安装 — 验证：npm --version，显示版本号 ✅ Opencode 已安装 — 验证：opencode --version，显示版本号 ✅ VS Code 已安装 — 验证：code --version，显示版本号 ✅ Miniconda 已安装 — 验证：conda --version，显示版本号 ✅ Pandoc 已安装 — 验证：pandoc --version，显示版本号

VS Code 插件（第四部分）

✅ Office Viewer — 搜索 cweijan.vscode-office，已安装 ✅ Git Graph — 搜索 mhutchie.git-graph，已安装 ✅ Marp for VS Code — 搜索 marp-team.marp-vscode，已安装

Opencode 功能（第三部分）

✅ Opencode 可以启动 — 输入 opencode，出现 TUI 界面 ✅ AI 连接正常 — 输入任意问题，AI 正常回复 ✅ Skills 扩展已安装 — 输入 /skills，列表中显示 15 个技能

Python 环境

✅ conda base 环境正常 — 打开新终端，提示符前出现 (base) ✅ Python 版本正确 — 验证：python --version，显示 Python 3.12.x

全部打勾，恭喜你完成了 Opencode AI 工作套装的完整安装！现在你可以在任意文件夹里输入 opencode 启动 AI 助手，开始工作了。

官方资源：

• Opencode 官网：opencode.ai
• 中文文档：opencode.ai/zh
• 学习网站：learnopencode.com
• Skills 扩展包：GitHub 仓库