OpenCode 终端 AI 编程助手实战教程

📚 分类: AI 编程工具 ⏱️ 预计耗时: 30-45 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Windows (WSL2) / Linux，稳定的网络连接

你将学到什么

完成本教程后，你将能够：

[ ] 成功安装并配置 OpenCode 终端 AI 编程助手
[ ] 掌握 OpenCode 的两种主要使用模式（TUI 和 Web）
[ ] 熟练使用 OpenCode 的核心 CLI 和 TUI 内置命令
[ ] 了解并安装 oh-my-openagent 插件，体验 AI 团队协作编程
[ ] 配置 MCP 服务，让 AI 具备联网搜索和文档查询能力

最终效果

你将在你的终端中成功启动一个名为 opencode 的 AI 编程助手。你可以像与一位资深程序员对话一样，通过自然语言让它帮你编写、调试、重构代码，甚至完成复杂的软件工程项目。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求版本	验证命令
Node.js	≥ 18.0	`node -v`
npm	≥ 9.0	`npm -v`
Git	≥ 2.30	`git --version`

1. 安装 Node.js 和 npm

如果你的系统尚未安装 Node.js 和 npm，请访问 Node.js 官网下载并安装最新的 LTS 版本。

✅ 验证：在终端中分别运行 node -v 和 npm -v，如果看到类似 v18.x.x 和 9.x.x 的输出，说明安装成功。

第 1 步：配置网络代理（可选但强烈推荐）

🎯 目标：为后续的安装和模型访问提供稳定、快速的网络连接。

由于网络环境限制，直接下载 Node.js 包或访问 AI 模型 API 可能很慢或失败。配置一个代理可以解决这个问题。

📝 操作：

注册代理服务：打开你的代理服务提供商网站，注册一个账号并购买一个合适的套餐。你会获得订阅链接。
安装代理客户端：根据服务商指引，下载并安装适用于你操作系统的代理客户端（如 Clash、Surge、V2Ray 等）。
导入订阅并开启代理：在客户端中导入你的订阅链接，然后将模式切换为「规则代理」或「全局代理」，最后点击「开启」。
验证代理：打开浏览器，访问 https://www.google.com。如果能正常打开，说明代理配置成功。
让终端使用代理：
- macOS / Linux：在终端中执行以下命令（将 PORT 替换为你代理客户端的端口，通常是 7890 或 1080）：
  bash
```
export https_proxy=http://127.0.0.1:PORT http_proxy=http://127.0.0.1:PORT all_proxy=socks5://127.0.0.1:PORT
```
- Windows (WSL)：在 WSL 终端中执行上面的 bash 命令。
- Windows (PowerShell)：在 PowerShell 中执行：
  powershell
```
$env:https_proxy="http://127.0.0.1:PORT"
$env:http_proxy="http://127.0.0.1:PORT"
```
- 提示：你可以在代理客户端的设置中找到「复制终端代理命令」的选项，直接粘贴使用更方便。

⚠️ 重要提示：每次打开一个新的终端窗口，都需要重新执行上述命令，代理才会生效。

✅ 验证：在配置了代理的终端中执行 curl -I https://www.google.com，如果返回 HTTP/2 200 等状态码，说明终端代理已生效。

第 2 步：安装 OpenCode

🎯 目标：在你的系统上成功安装 opencode 命令行工具。

📝 操作：

根据你的操作系统，选择以下一种方式安装。

方式一：使用 npm 安装（推荐，适用于所有平台）

bash

$ npm install -g opencode-ai        // 全局安装 opencode

方式二：macOS 使用 Homebrew 安装

bash

$ brew install anomalyco/tap/opencode

方式三：使用一键安装脚本（适用于 macOS / Linux / WSL）

bash

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

💡 提示：如果安装过程中遇到权限错误（如 EACCES），在 macOS / Linux 命令前加 sudo，或在 Windows 上以管理员身份运行终端。

✅ 验证：安装完成后，运行以下命令确认版本：

bash

$ opencode -v

预期输出：

text

1.2.24     // 版本号可能不同

第 3 步：配置模型提供商

🎯 目标：让 OpenCode 知道该调用哪个 AI 模型来为你服务。

OpenCode 本身不包含 AI 模型，它需要连接到一个模型提供商（如 OpenAI、Anthropic 等）的 API。你需要一个 API Key。

📝 操作：

创建配置文件：
bash
```
$ mkdir -p ~/.config/opencode        // 创建配置目录
$ code ~/.config/opencode/opencode.jsonc  // 用 VS Code 打开配置文件（推荐）
```
💡 提示：如果没有 code 命令，可以用 nano 或 vim 替代。Windows 用户也可以直接在资源管理器的地址栏输入 \\wsl$\Ubuntu\home\你的WSL用户名\.config\opencode 来编辑。

编辑配置文件：将以下内容粘贴到 opencode.jsonc 文件中。

json

{
  "$schema": "https://opencode.ai/config.json",  // 提供智能提示和自动补全
  "model": {
    "provider": "openai",                        // 选择模型提供商，如 openai, anthropic, google
    "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // 替换为你的真实 API Key
    "apiKey": "YOUR_API_KEY_HERE"               // 替换为你的真实 API Key
  }
}

🤔 为什么要这样做？ provider 告诉 OpenCode 要连接哪个服务商，apiKey 是访问该服务的凭证。没有这些，OpenCode 无法工作。

保存文件。

✅ 验证：在终端中运行 opencode。如果配置正确，你将进入 OpenCode 的 TUI 交互界面。首次启动可能需要几秒钟来初始化。

第 4 步：使用 OpenCode（TUI 模式）

🎯 目标：熟悉 OpenCode 最常用的终端交互界面。

📝 操作：

启动 TUI：
bash
```
$ opencode
```
你将看到一个类似于聊天界面的终端窗口。

开始对话：在底部的输入框中输入你的第一个指令，例如：

text

用 Python 写一个简单的 Web 服务器，监听 8080 端口，返回 "Hello, OpenCode!"

查看结果：AI 会分析你的请求，生成代码，并显示在界面上。你可以看到它创建文件、编写代码的整个过程。
退出 TUI：输入 /exit 或按 Ctrl + C 即可退出。

✅ 验证：AI 成功生成并创建了包含你所需功能的 Python 文件。

第 5 步：掌握常用命令

🎯 目标：学习 OpenCode 最常用的命令，提高你的工作效率。

5.1 CLI 命令（在终端中直接输入）

命令	说明
`opencode`	启动 TUI 交互界面（最常用）
`opencode -v`	显示版本号
`opencode -h`	显示帮助信息
`opencode upgrade`	升级到最新版本
`opencode run "你的提示"`	非交互模式，快速执行单次任务
`opencode models`	列出所有可用模型
`opencode session list`	查看历史会话
`opencode -s <session_id>`	使用指定会话
`opencode serve`	启动无头服务器（供 Desktop / Web 连接）
`opencode web`	启动 Web 界面
`opencode stats`	查看 Token 使用统计

5.2 TUI 内置命令（进入界面后输入 `/`）

命令	说明
`/connect`	连接或切换模型提供商
`/models`	查看并切换模型
`/init`	初始化项目（生成 AGENTS.md）
`/new`	新建会话
`/compact`	手动压缩上下文
`/undo`	撤销上一步操作
`/redo`	重做
`/share`	生成分享链接
`/help`	显示所有命令

进阶技巧（可选）

1. 安装 oh-my-openagent 插件，体验 AI 团队

oh-my-openagent（OMO）是一个强大的多代理插件，它可以将 OpenCode 从一个单一 AI 助手升级为一个由多个专业 AI 代理组成的「开发团队」。

安装：在 OpenCode 的 TUI 界面中，直接发送以下指令：

text

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

AI 会自动完成安装和配置。安装成功后，重启 OpenCode，你会看到界面提示已切换到 Sisyphus (Ultraworker) 模式。

2. 配置 MCP 服务，让 AI 联网搜索

MCP (Model Context Protocol) 允许 AI 模型访问外部工具和数据源，例如实时搜索网页或查询文档。

在 opencode.jsonc 文件中添加 mcp 字段来配置服务：

json

{
  "$schema": "https://opencode.ai/config.json",
  "model": {
    "provider": "openai",
    "apiKey": "YOUR_API_KEY_HERE"
  },
  "mcp": {
    "context7": {                              // 官方文档查询
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    },
    "gh_grep": {                               // GitHub 代码搜索
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

常见问题 (FAQ)

Q1: 运行 opencode 后报错 API Key 无效 怎么办？A: 检查配置文件 ~/.config/opencode/opencode.jsonc 中的 apiKey 是否正确。确保你没有复制多余的空格或引号。如果确认 Key 无误，请检查 API 提供商账户是否余额充足。

Q2: 安装 npm install -g opencode-ai 时卡住或报错 ETIMEDOUT？A: 这是网络问题。请参考【第 1 步】正确配置终端代理，然后重试。也可以尝试切换到其他网络环境。

Q3: 如何修改 OpenCode 使用的模型？A: 在 TUI 界面中输入 /connect，按照提示选择或切换模型提供商。或者，直接输入 /models 查看并切换当前提供商下的不同模型。

Q4: 如何删除历史会话？A: 目前没有直接的删除命令。你可以手动删除配置文件所在目录下的 sessions 文件夹（通常是 ~/.config/opencode/sessions）。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

安装与配置：你学会了如何通过 npm 安装 opencode，并配置模型提供商和网络代理。
核心使用：你掌握了 opencode 的 TUI 和 Web 两种使用模式，以及最常用的 CLI 和 TUI 内置命令。
进阶扩展：你了解了如何通过安装 oh-my-openagent 插件和配置 MCP 服务，来大幅扩展 OpenCode 的能力。

下一步

如果你想继续深入，建议学习：

📖 oh-my-openagent 官方文档：深入学习如何配置和使用其强大的多代理功能。
📖 MCP 协议官方文档：了解如何创建和使用自定义 MCP 服务，将更多工具集成到你的 AI 工作流中。

💡 练习任务：尝试使用 OpenCode 重构你之前写过的某个小项目。比如，让它帮你添加新功能、修复 bug 或优化代码结构。这是巩固知识的最佳方式。

yaml


## 相关文档

- [终端 AI 编程实战指南：Claude Code 与 OpenCode 双工具上手](/docs/chu-ci-shi-yong/zhong-duan-ai-bian-cheng-shi-zhan-zhi-nan-claude-code-yu-opencode-shuang-gong-ju-shang-shou.html)
- [OpenCode Zen 实战教程：快速接入精选 AI 模型](/docs/chu-ci-shi-yong/opencode-zen-shi-zhan-jiao-cheng-kuai-su-jie-ru-jing-xuan-ai-mo-xing.html)
- [OpenCode 实战教程：在终端里玩转 AI 编程助手](/docs/chu-ci-shi-yong/opencode-shi-zhan-jiao-cheng-zai-zhong-duan-li-wan-zhuan-ai-bian-cheng-zhu-shou.html)

OpenCode 终端 AI 编程助手 实战教程 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 安装 Node.js 和 npm ​

第 1 步：配置网络代理（可选但强烈推荐） ​

第 2 步：安装 OpenCode ​

第 3 步：配置模型提供商 ​

第 4 步：使用 OpenCode（TUI 模式） ​

第 5 步：掌握常用命令 ​

5.1 CLI 命令（在终端中直接输入） ​

5.2 TUI 内置命令（进入界面后输入 /） ​

进阶技巧（可选） ​

1. 安装 oh-my-openagent 插件，体验 AI 团队 ​

2. 配置 MCP 服务，让 AI 联网搜索 ​

常见问题 (FAQ) ​

总结 ​

下一步 ​

OpenCode 终端 AI 编程助手实战教程

你将学到什么

最终效果

前置准备

1. 安装 Node.js 和 npm

第 1 步：配置网络代理（可选但强烈推荐）

第 2 步：安装 OpenCode

第 3 步：配置模型提供商

第 4 步：使用 OpenCode（TUI 模式）

第 5 步：掌握常用命令

5.1 CLI 命令（在终端中直接输入）

5.2 TUI 内置命令（进入界面后输入 `/`）

进阶技巧（可选）

1. 安装 oh-my-openagent 插件，体验 AI 团队

2. 配置 MCP 服务，让 AI 联网搜索

常见问题 (FAQ)

总结

下一步