OpenCode 终端AI助手实战教程：从零搭建你的AI编程团队

📚 分类: AI | 开发工具 | 终端 ⏱️ 预计耗时: 45-60 分钟 🎯 难度: 入门到中级 🔧 环境要求: macOS / Linux / Windows (WSL2)

你将学到什么

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

[ ] 掌握 OpenCode 的安装与核心配置，使其能连接你选择的AI模型。
[ ] 熟练使用 OpenCode 的终端交互界面 (TUI) 和常用命令。
[ ] 理解并配置 oh-my-openagent 插件，将一个AI助手升级为一个多角色AI编程团队。
[ ] 搭建一个包含模型提供商、代理插件和外部工具 (MCP) 的完整AI编程环境。

最终效果

你将在终端中拥有一个强大的AI编程助手。输入 opencode 进入交互界面，你可以像跟同事聊天一样，让它帮你写代码、查Bug、重构项目。安装 oh-my-openagent 后，它甚至能变成一个由多个专业AI代理（如规划师、编码员、审查员）组成的团队，自主完成复杂的软件开发任务。

前置准备

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

环境要求：

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

1. 安装 Node.js 和 npm

如果你的系统没有 Node.js，请访问 Node.js 官网下载当前最新稳定版 (LTS) 并安装。安装包会自动包含 npm。

✅ 验证：在终端运行 node -v 和 npm -v，应看到版本号输出。

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

🎯 目标：确保后续下载 Node.js 包和 OpenCode 安装脚本的速度，避免因网络问题导致失败。

🤔 为什么要这样做？ 许多开发者工具和资源托管在海外服务器，国内网络环境下直接下载可能非常缓慢或连接失败。配置一个稳定的代理可以显著提升体验。

📝 操作：

获取代理服务：
- 访问你选择的代理服务商网站，完成注册、购买和客户端下载。
- 根据服务商指引，下载并安装其客户端软件。
配置代理客户端：
- 打开已安装的代理软件。
- 找到“导入订阅”或类似功能，并执行导入。
- 将代理模式切换到 “规则代理” 或 “全局代理”。
- 点击“连接”或“开启”按钮。
✅ 验证：打开浏览器，访问 www.google.com。如果页面能正常加载，说明代理配置成功。
为终端设置代理：
- 在代理软件的设置中，找到 “复制终端代理命令” 或类似选项。
- Mac用户：选择 bash 或 zsh 类型。
- Windows (WSL) 用户：选择 bash 类型。
- 复制该命令，然后粘贴到你的 新终端窗口 中并执行。
💡 提示：此代理设置只在当前终端窗口有效。每次打开新终端都需要重新执行此命令。
⚠️ 常见错误：
- 症状：仍然无法访问某些网站。
- 原因：可能没有选择正确的终端类型，或者代理软件未正确开启。
- 解决：检查代理软件连接状态，并确保复制的命令与你的终端类型 (bash/zsh) 匹配。

第 2 步：安装 OpenCode

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

📝 操作：根据你的操作系统选择一种安装方式。

选项 A：macOS 用户

打开终端，任选其一：

方式一：Homebrew (官方推荐)
bash
```
$ brew install anomalyco/tap/opencode
```

方式二：一键安装脚本

bash

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

方式三：npm (通用)
bash
```
$ npm install -g opencode-ai
```

选项 B：Windows 用户

Windows 用户的最佳体验是通过 WSL (Windows Subsystem for Linux)。请确保你已安装 WSL2。

启动 WSL：
- 以管理员身份打开 PowerShell 或 Windows 终端。
- 运行以下命令安装 WSL (如果尚未安装)：
  bash
```
$ wsl --install
```
- 安装完成后，重启计算机。
- 重启后，再次打开 PowerShell，运行 wsl 进入 Linux 环境。根据提示设置你的 Linux 用户名和密码。
- 更新软件源：
  bash
```
$ sudo apt update && sudo apt upgrade -y
```
- 安装必要依赖：
  bash
```
$ sudo apt install -y curl git
```
安装 OpenCode：
- 在 WSL 终端中，运行一键安装脚本：
  bash
```
$ curl -fsSL https://opencode.ai/install | bash
```

✅ 验证：安装完成后，在终端中输入以下命令：

bash

$ opencode -v

你应该会看到类似 1.2.4 的版本号输出。如果看到此信息，恭喜你，安装成功！

第 3 步：配置 OpenCode 连接AI模型

🎯 目标：创建一个配置文件，告诉 OpenCode 应该连接到哪个AI模型服务商。

OpenCode 本身不包含AI模型，你需要配置一个“提供商” (Provider) 来连接。这里我们以配置一个兼容 OpenAI API 的第三方服务 (CPA) 为例。

📝 操作：

创建配置文件：
- macOS / Linux / WSL：在终端中运行以下命令创建并编辑配置文件。
  bash
```
$ mkdir -p ~/.config/opencode && nano ~/.config/opencode/opencode.jsonc
```
  💡 你也可以使用 code ~/.config/opencode/opencode.jsonc (VS Code) 或 vim 等编辑器。

填入配置内容：

将以下 JSON 内容复制到文件中，并根据你的实际情况修改 baseURL 和 apiKey 的值。

jsonc

{
    "$schema": "https://opencode.ai/config.json",
    "disabled_providers": ["google-vertex", "google-vertex-anthropic"], // 禁用官方提供商
    "provider": {
        "cpa": { // 自定义提供商名称，这里叫 "cpa"
            "name": "CPA",
            "npm": "@ai-sdk/openai-compatible", // 指定兼容 OpenAI 的 SDK
            "options": {
                "baseURL": "你的服务地址/v1", // 替换为你的服务地址
                "apiKey": "你的 API Key" // 替换为你的 API Key
            },
            "models": {
                "gpt-latest": {
                    "name": "gpt-latest(high)", // 模型名称，可自定义
                    "cost": {
                        "input": 2.5,
                        "output": 15,
                        "cache_read": 0.25,
                        "cache_write": 0,
                        "context_over_200k": {
                            "input": 5,
                            "output": 22.5,
                            "cache_read": 0.5,
                            "cache_write": 0
                        }
                    }
                },
                "gpt-codex-latest": {
                    "name": "gpt-codex-latest(xhigh)",
                    "cost": {
                        "input": 1.75,
                        "output": 14,
                        "cache_read": 0.175,
                        "cache_write": 0
                    }
                }
            }
        }
    },
    "autoupdate": true
}

🤔 为什么要这样配置？

disabled_providers: 禁用 OpenCode 内置的、但我们无法使用的官方模型提供商。
provider: 定义我们自己的模型提供商。@ai-sdk/openai-compatible 允许我们连接任何兼容 OpenAI API 的服务。
models: 定义可用的模型。gpt-latest 指向最新的GPT模型，gpt-codex-latest 指向专门的代码模型。cost 字段用于跟踪 Token 消耗，对成本控制很重要。

✅ 验证：保存文件后，在终端运行 opencode models。你应该能看到 cpa/gpt-latest 和 cpa/gpt-codex-latest 出现在列表中。

第 4 步：启动并使用 OpenCode

🎯 目标：体验 OpenCode 的两种主要使用模式。

📝 操作：

进入项目目录：

macOS / Linux：
bash
```
$ cd ~/my-project
```

Windows (WSL)：

bash

$ cd /mnt/c/Users/你的Windows用户名/my-project

启动终端模式 (TUI)：
- 这是最常用的模式。在项目目录中直接输入：
  bash
```
$ opencode
```
- 你会进入一个类似聊天界面的终端窗口。在这里，你可以开始向AI提问或下达指令。
启动 Web 模式：
- 如果你更喜欢图形界面，可以启动 Web 模式：
  bash
```
$ opencode web
```
- 系统会启动一个本地服务器，并自动在浏览器中打开一个网页版的聊天界面。

✅ 验证：

TUI模式：你应该看到类似 > 的提示符，等待你输入。
Web模式：浏览器中应打开一个带有输入框和对话区域的页面。
💡 提示：第一次启动时，OpenCode 可能会提示你选择模型。选择我们在上一步配置的 cpa/gpt-latest 或 cpa/gpt-codex-latest。

第 5 步：掌握常用命令

🎯 目标：了解并使用 OpenCode 的核心命令，提高工作效率。

📝 操作：

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

命令	说明	示例
`opencode`	启动 TUI 交互界面	`opencode`
`opencode run "你的提示"`	非交互模式，快速执行单次任务	`opencode run "用Python写一个斐波那契数列函数"`
`opencode -v`	显示版本号	`opencode -v`
`opencode upgrade`	升级到最新版本	`opencode upgrade`
`opencode session list`	查看历史会话列表	`opencode session list`
`opencode -s <session_id>`	使用指定会话ID继续对话	`opencode -s abc123`

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

进入 TUI 界面后，输入 / 可以执行内部命令。

命令	说明
`/connect`	连接或切换模型
`/models`	查看并切换当前使用的模型
`/new`	新建一个会话
`/undo`	撤销上一步AI的操作
`/help`	显示所有可用命令

第 6 步：进阶配置 - 安装 oh-my-openagent 插件 (打造AI团队)

🎯 目标：将 OpenCode 从单一的AI助手升级为一个可以自主规划、编码、审查的多代理团队。

oh-my-openagent (OMO) 是 OpenCode 生态中最强大的插件之一。它引入了“Sisyphus”主协调代理，可以调度多个专业子代理（如编码员 hephaestus、规划师 prometheus、审查员 momus）并行工作。

📝 操作：

自动安装：
- 启动 OpenCode TUI 界面 (opencode)。
- 在提示符下，直接输入以下内容并发送：
```
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 会自动读取安装指南并执行安装。你只需等待它完成即可。

手动配置模型 (重要！)：

OMO 默认配置使用的是官方模型 (如Claude、GPT)，我们需要将其修改为我们自己的 cpa 提供商。
编辑 OMO 的配置文件：
bash
```
$ code ~/.config/opencode/oh-my-opencode.json
```
如果找不到 oh-my-opencode.json 文件，可以先尝试安装一次，或者手动创建。
将文件内容替换为以下配置：

jsonc

{
    "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/assets/oh-my-opencode.schema.json",
    "agents": {
        "sisyphus": { "model": "cpa/gpt-latest", "variant": "high" },
        "hephaestus": { "model": "cpa/gpt-codex-latest", "variant": "xhigh" },
        "oracle": { "model": "cpa/gpt-latest", "variant": "xhigh" },
        "librarian": { "model": "cpa/gpt-codex-latest", "variant": "high" },
        "explore": { "model": "cpa/gpt-codex-latest", "variant": "high" },
        "multimodal-looker": { "model": "cpa/gpt-latest", "variant": "high" },
        "prometheus": { "model": "cpa/gpt-latest", "variant": "xhigh" },
        "metis": { "model": "cpa/gpt-latest", "variant": "xhigh" },
        "momus": { "model": "cpa/gpt-latest", "variant": "xhigh" },
        "atlas": { "model": "cpa/gpt-latest", "variant": "high" }
    },
    "categories": {
        "visual-engineering": { "model": "cpa/gpt-latest", "variant": "high" },
        "ultrabrain": { "model": "cpa/gpt-latest", "variant": "xhigh" },
        "deep": { "model": "cpa/gpt-codex-latest", "variant": "xhigh" },
        "artistry": { "model": "cpa/gpt-latest", "variant": "high" },
        "quick": { "model": "cpa/gpt-codex-latest", "variant": "high" },
        "unspecified-low": { "model": "cpa/gpt-codex-latest", "variant": "high" },
        "unspecified-high": { "model": "cpa/gpt-latest", "variant": "high" },
        "writing": { "model": "cpa/gpt-latest", "variant": "high" }
    }
}

🤔 为什么要这样配置？

agents 部分定义了不同角色的AI代理。例如，hephaestus (编码员) 使用了专门的代码模型 gpt-codex-latest 并设置为最高努力级别 xhigh，以进行深度编码。
categories 部分定义了任务分类。当任务被归类为 quick (快速任务) 时，会使用成本更低的 gpt-codex-latest 模型。

✅ 验证：重启 OpenCode。如果启动后提示“Sisyphus (Ultraworker)”或其他代理已就绪，则说明安装成功。你现在可以尝试输入一个复杂任务，例如“ulw 帮我创建一个简单的React待办事项应用”，观察AI团队如何协作。

⚠️ 常见错误：

症状：OMO 无法正常工作，或提示找不到模型。
原因：oh-my-opencode.json 中的模型名称 (如 cpa/gpt-latest) 与 opencode.jsonc 中的定义不匹配。
解决：仔细检查两个配置文件中定义的模型名称是否完全一致。

进阶技巧 (可选)

配置 MCP 服务 (增强AI能力)

MCP (Model Context Protocol) 允许 OpenCode 连接外部工具，如搜索引擎、文档库等。

编辑 OpenCode 配置文件：

bash

$ code ~/.config/opencode/opencode.jsonc

添加 MCP 配置：在文件末尾，autoupdate 字段之后，添加 mcp 字段。以下是一个组合配置示例，添加了文档查询和代码搜索服务。

jsonc

{
    // ... 其他配置 (provider等)
    "autoupdate": true,
    "mcp": {
        "context7": { // 官方文档查询
            "type": "remote",
            "url": "https://mcp.context7.com/mcp"
        },
        "gh_grep": { // GitHub 代码搜索
            "type": "remote",
            "url": "https://mcp.grep.app"
        }
    }
}

💡 提示：MCP 服务会消耗 Token，建议只启用当前需要的服务。你可以通过 opencode mcp list 查看已配置的服务。

常见问题 (FAQ)

Q1: 安装 OpenCode 时报错 EACCES: permission denied 怎么办？

A: 这是权限错误。在 Mac/Linux 上，尝试在命令前加 sudo (例如 sudo npm install -g opencode-ai)。在 Windows 上，请确保以管理员身份运行 PowerShell 或终端。

Q2: 启动 OpenCode 后，提示 Model not found 或 Provider not configured？

A: 说明配置文件中模型名称或提供商设置错误。请仔细检查 ~/.config/opencode/opencode.jsonc 文件，确保 provider 下的模型名称与你启动时选择的模型一致。运行 opencode models 可以查看所有可用模型。

Q3: 运行 opencode 后，界面卡住或没有响应？

A: 这通常是因为网络连接问题。请确保你的代理配置正确且已生效。如果使用了代理，检查代理软件是否正常运行，并重新在终端中执行代理环境变量命令。

Q4: 如何将 OpenCode 用于我的现有项目？

A: 非常简单！只需在终端中 cd 到你的项目根目录，然后运行 opencode。OpenCode 会自动读取你的项目文件，并基于项目上下文为你提供帮助。

总结

恭喜你完成了本教程！🎉

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

安装与配置：你学会了如何安装 OpenCode，并配置它连接自定义的AI模型提供商。
核心使用：你掌握了 TUI 和 Web 两种模式，以及常用的 CLI 和内置命令。
进阶插件：你成功安装了 oh-my-openagent 插件，将你的AI助手升级为一个多代理团队。
生态扩展：你了解了如何通过 MCP 服务为 AI 添加更多外部能力。

下一步

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

📖 深入 oh-my-openagent：尝试使用 /init-deep 命令初始化项目，或使用 /ulw-loop 进行复杂的迭代开发。
📖 掌握 MCP：探索更多 MCP 服务，如 Exa (网页搜索) 和 Playwright (浏览器自动化)，打造更强大的AI工具链。
📖 学习 Skill 系统：尝试安装 ui-ux-pro-max 等技能，让 AI 在特定领域 (如前端开发) 表现得更加专业。

💡 练习任务：尝试使用 OpenCode 和 oh-my-openagent 插件，从头开始创建一个简单的个人博客网站。这是将所学知识融会贯通的最佳方式。

yaml

OpenCode 终端AI助手 实战教程：从零搭建你的AI编程团队 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 安装 Node.js 和 npm ​

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

第 2 步：安装 OpenCode ​

选项 A：macOS 用户 ​

选项 B：Windows 用户 ​

第 3 步：配置 OpenCode 连接AI模型 ​

第 4 步：启动并使用 OpenCode ​

第 5 步：掌握常用命令 ​

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

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

第 6 步：进阶配置 - 安装 oh-my-openagent 插件 (打造AI团队) ​

进阶技巧 (可选) ​

配置 MCP 服务 (增强AI能力) ​

常见问题 (FAQ) ​

总结 ​

下一步 ​

OpenCode 终端AI助手实战教程：从零搭建你的AI编程团队

你将学到什么

最终效果

前置准备

1. 安装 Node.js 和 npm

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

第 2 步：安装 OpenCode

选项 A：macOS 用户

选项 B：Windows 用户

第 3 步：配置 OpenCode 连接AI模型

第 4 步：启动并使用 OpenCode

第 5 步：掌握常用命令

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

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

第 6 步：进阶配置 - 安装 oh-my-openagent 插件 (打造AI团队)

进阶技巧 (可选)

配置 MCP 服务 (增强AI能力)

常见问题 (FAQ)

总结

下一步