一、OpenCode 是什么？

1.1 概述

OpenCode 是一个开源的 AI 编程代理（AI Coding Agent），它允许开发者在终端、桌面应用或 IDE 扩展中直接与 AI 协作，完成代码编写、Bug 修复、项目重构等任务。你可以在命令行里直接和它对话，让它帮你写代码、理解代码、找 Bug、做重构，整个过程无需切换到浏览器或复制粘贴。

1.2 核心特点

1.3 与 Claude Code 的区别

OpenCode 和 Claude Code 都是终端 AI 编程工具，但两者还是有着有很大的区别。下面是OpenCode 和 Claude Code的差异对比，可以看到OpenCode 的工具本身完全免费，用户只需要为自己使用的模型 API 付费。这种模式为降本提供了极大的灵活性，可以使用便宜的开源模型处理简单任务。如果你追求灵活性、可控性和开源自由，OpenCode 显然是更好的选择。

二、安装前准备

2.1 系统要求

在安装 OpenCode 之前，请确保你的环境满足以下要求：

2.2 检查 Node.js 版本

OpenCode 是基于 JavaScript 编写的命令行工具，且底层依赖 Bash 环境运行。因此需要先安装Node.js，Node.js 是OpenCode工具运行的基础环境。打开终端，输入以下命令检查 Node.js 版本：

>node -v
v23.9.0

如果显示 v18.x.x 或更高版本，说明满足要求。如果没有安装或版本过低，请前往 Node.js 官网 下载安装 LTS 版本。

2.2.1 安装 Node.js

Node.js 是一个基于 Chrome V8 引擎的开源、跨平台的 JavaScript 运行时环境。它让 JavaScript 能够脱离浏览器，在服务器端运行，从而可以用 JavaScript 开发后端应用。安装 Node.js 时会同时附带安装 npm（Node Package Manager），用于管理 JavaScript 依赖包。访问 Node.js 官网，你会看到两个版本：

提议选择 LTS 版本，稳定性更好，兼容性问题更少。

2.2.2 下载Node.js安装包（Windows版本）

打开 Node.js 官网：https://nodejs.org，点击 LTS 版本的 Windows 安装包（.msi 文件）进行下载如果需要下载历史版本，可以在官网页面找到“Previous Releases”入口。

2.2.3 安装步骤

1. 双击下载好的 .msi 安装包，启动安装向导
2. 勾选 “I accept the terms in the License Agreement”，点击 Next 继续
3. 选择安装路径：默认安装在 C:Program Files
   odejs
4. 提议修改到其他盘符（如 D:Develop
   odejs），避免占用 C 盘空间（路径中不要包含中文、空格或特殊字符）
5. 保持默认组件选择，点击 Next（默认会安装 npm 和添加到 PATH）
6. 勾选 “Automatically install the necessary tools”（可选，用于编译原生模块），点击 Next
7. 点击 Install 开始安装
8. 安装完成后，点击 Finish 退出向导即可

2.3 准备 API 密钥

OpenCode本身只是一个开源的 AI 编程代理工具，并没有提供 AI 模型。它需要通过 API 连接到大型语言模型才能工作，所以你需要先从第三方服务商获取对应大模型的 API 密钥。

三、安装 OpenCode（Windows版本）

3.1 npm安装

前面我们已经安装了 Node.js ，目前可以使用 npm 进行全局安装。打开 Windows 的 CMD (命令提示符)，输入以下命令并回车：

# 使用 npm 安装opencode
npm install -g opencode-ai
# 或者
npm install -g opencode-ai@latest

当然你也可以使用pnpm 和 Bun来安装，pnpm 和 Bun 都是新一代 JavaScript 包管理工具/运行时，相比传统 npm 有以下优势：

3.2 验证安装

安装完成后，运行以下命令验证是否安装成功：

# 安装完成后，通过以下命令确认安装成功
# 查看版本信息
opencode --version
# 获取完整功能协助
opencode --help

如果显示版本号（如 v1.3.5），说明安装成功。

3.3 VSCode集成

启动 Visual Studio Code程序，在侧边栏中点击扩展图标。在顶部的搜索框中输入需要安装的扩展的名称：opencode，从搜索结果中选择 SST提供的opencode扩展，然后点击“安装”按钮。安装完成后按快捷键ctrl+shift+p打开打开命令面板，输入open opencode 确认侧边就会出现opencode的命令行窗口。

四、首次配置

4.1 启动 OpenCode

打开 Windows 的 CMD (命令提示符)，使用cd命令进入你的项目目录。之后执行命令 OpenCode启动OpenCode，OpenCode 会以当前目录作为项目上下文。界面顶部是状态栏（显示当前模型、会话 ID、网络状态），中部是双 Tab 区域（build / plan），底部是命令提示行。

4.2 连接 AI 模型

启动后你会看到 OpenCode 的文本用户界面（TUI），接下来需要连接 AI 模型：

1. 在对话框中输入/connect，选择弹出的 Connect Provider 选项。
2. 从提供商列表中选择你要使用的 LLM 服务商（如 OpenAI、Anthropic、Alibaba 等）
3. 按提示输入你的 API 密钥
4. 选择要使用的具体模型（如 gpt-4、claude-3.5-sonnet、qwen3-coder-plus）

4.2.1 免费模型

OpenCode 内置了许多免费模型主要包括 GPT-5 Nano、Big Pickle、GLM-4.7、Grok Code Fast 1 和 MiniMax M2.1（或 M2.5 Free）等，这些模型可通过其官网（opencode.ai）或命令行工具直接使用并无需配置 API 密钥。在对话框中输入/models选择Switch Models，通过键盘的上下按键可以查看各种模型。右侧显示free的就是当前的免费模型，选中后直接按下enter键即可确认模型更改。

4.3 初始化项目

在 OpenCode 终端交互界面（TUI）中，输入 /init 可以对当前项目进行初始化。该命令会分析当前项目的代码结构、依赖和编码风格，并在项目根目录下生成一个 AGENTS.md 文件。这个文件存储了项目的上下文信息，能协助 AI 更好地理解项目需求。同时生成一个 .opencode/ 文件夹，用于存储项目的向量化索引和自定义指令。

五、基本使用

5.1 运行模式

OpenCode 内置了两个代理（Agent），可以通过 Tab 键 在它们之间切换。打开新代码时可以先用 plan 模式了解项目结构，确认无误后再切换到 build 模式进行修改。

5.2 常用命令

在 OpenCode 的交互界面中，以 / 开头的命令可以快速执行特定功能。

5.3 Session 管理

Session（会话）管理是opencode的核心功能之一，每个会话都是一个独立的工作空间。每个会话拥有自己的对话历史、文件上下文和内存状态。通过不同的Session可以让你高效地并行处理多个任务，同时确保上下文清晰、资源消耗可控。

1. 列出会话
   opencode session list：打印所有会话记录。
   opencode session list –max-count 10：限制输出数量。
   opencode session list –format json：以 JSON 格式输出，方便脚本处理。
2. 恢复与分支
   opencode –continue：快速恢复最后一次活跃的会话。
   opencode –session <SessionID>：加载指定的会话。
   opencode –session <SessionID> –fork：克隆会话。基于指定会话的状态创建一个新分支，后续操作不会影响原始会话。
3. 删除会话
   opencode session delete <SessionID>：删除指定会话。
   opencode session delete –all：清空所有本地会话记录。
4. 重命名会话
   为了方便识别，你可以为会话添加可读的标签。例如，在会话中执行以下命令，可以将其重命名为“用户中心重构”：
   opencode session rename –current “用户中心重构”。

5.4 时间线管理

这个功能等于一个内置的、可视化的 Git 版本管理器，可以清晰地看到 AI 对代码的每一次修改。能随时将项目恢复到任何一个历史状态，代码和聊天都能回到那个时间点。

六、总结

OpenCode 是一款功能强劲、开源免费的 AI 编程助手，它将 AI 能力无缝集成到终端工作流中。无论你是全栈开发者、独立开发者还是开源贡献者，OpenCode 都能帮你提升编码效率，让你更专注于解决真正的问题。如果你在安装过程中遇到任何报错，欢迎在评论区留言，我会尽力解答。别忘了点赞收藏，这对我超级重大！我们下期再见！