OpenCode AI 编码代理实战教程
📚 分类: AI 开发工具 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 一台能联网的电脑 (Windows / macOS / Linux)
你将学到什么
完成本教程后，你将能够：
- [ ] 在本地成功安装并启动 OpenCode 终端界面
- [ ] 配置你的第一个 AI 模型提供商（获取并设置 API 密钥）
- [ ] 让 OpenCode 分析你的项目代码并为你解释
- [ ] 使用“计划-构建”模式，让 AI 为项目安全地添加新功能
- [ ] 撤销不想要的修改，并分享你的对话记录
最终效果
你将在终端中打开一个名为 OpenCode 的 AI 编码代理。它能理解你的项目结构，并能根据你的文本指令，直接读取、修改和创建代码文件。你将学会通过 /init 命令让 AI 了解你的项目，并通过自然语言与它协作编程，就像拥有一个随时待命的编程搭档。
前置准备
在开始前，请确认你的环境满足以下条件：
| 检查项 | 要求版本 | 验证命令 |
|---|---|---|
| 操作系统 | Windows 10+ / macOS 12+ / Linux | - |
| 终端模拟器 | 现代终端（如 Windows Terminal, iTerm2） | - |
| 网络 | 可以正常访问互联网 | - |
1. 安装一个现代终端（可选但推荐）
OpenCode 的界面在功能强大的终端中效果最佳。如果你不确定，可以跳过此步，使用系统自带的终端。
- Windows: 推荐安装 Windows Terminal 或 WezTerm。
- macOS: 推荐使用 iTerm2 或 WezTerm。
- Linux: 系统自带的
gnome-terminal或konsole通常就够用。
2. 获取一个 API 密钥
OpenCode 本身不提供 AI 模型，它需要调用外部的大语言模型（LLM）来理解你的意图和生成代码。因此，你需要一个外部 AI 提供商的 API 密钥，这相当于你访问这些模型的“门票”。
- 推荐（新手友好）: 注册 OpenCode Zen 服务。这是官方推荐的、经过测试的模型集合，使用最简单。
- 其他选项: 如果你已有 OpenAI、Anthropic 或其他兼容提供商的 API 密钥，也可以直接使用。
第 1 步：安装 OpenCode
🎯 目标：在你的电脑上成功安装 opencode 命令，并能在终端中运行它。
📝 操作：
打开你的终端，执行以下命令。这是最通用的安装方式。
$ curl -fsSL https://opencode.ai/install | bash
# 这行命令会下载并运行官方的安装脚本💡 如果你遇到网络问题，可以尝试以下备选方案之一：
方案 A：使用 npm（如果你已安装 Node.js）
$ npm install -g opencode-ai // 全局安装 opencode 包方案 B：在 macOS 上使用 Homebrew
$ brew install anomalyco/tap/opencode方案 C：在 Windows 上使用 Chocolatey
$ choco install opencode✅ 验证：
安装完成后，在终端中输入以下命令：
$ opencode --version你应当看到类似以下的输出：
opencode/0.x.x💡 提示：如果命令找不到，你可能需要重启终端或重新加载你的 shell 配置文件（如 source ~/.zshrc）。
第 2 步：配置 API 密钥
🎯 目标：告诉 OpenCode 应该使用哪个 AI 模型，并授权它使用你的 API 密钥。
📝 操作：
在终端中直接输入
opencode命令并回车，启动 OpenCode 的终端界面（TUI, Terminal User Interface）。bash$ opencode你会看到一个类似聊天界面的窗口。在输入框中输入
/connect命令并回车。text> /connect界面会提示你选择提供商。使用键盘的上下方向键选择
opencode（推荐新手），然后回车。系统会提示你输入 API 密钥，并提供一个链接（
https://opencode.ai/auth）。- 操作：用浏览器打开这个链接。
- 操作：登录或注册一个 OpenCode Zen 账号，并按照指引生成一个 API 密钥。
- 操作：复制这个密钥，回到终端，粘贴到输入框中（粘贴时可能不会显示字符，这是安全设计），然后回车。
text┌ API key │ │ [你粘贴的密钥] └ enter
✅ 验证：
如果密钥正确，你会看到一条连接成功的消息，并且界面右下角可能会显示你选择的模型名称。至此，OpenCode 已经准备好为你工作了。
🤔 为什么要这样做？ OpenCode 本身是一个“壳”，它需要调用大语言模型（LLM）来理解你的意图和生成代码。API 密钥就是你访问这些模型的“门票”。
第 3 步：初始化你的项目
🎯 目标：让 OpenCode 理解你当前项目的结构和规范，为后续的智能操作打好基础。
📝 操作：
首先，退出当前的 OpenCode 会话（按
Esc或Ctrl+C可以退出）。导航到你想要处理的项目目录。例如，如果你有一个名为
my-app的项目：bash$ cd /path/to/your/my-app再次启动 OpenCode：
bash$ opencode在 OpenCode 的聊天输入框中，输入
/init命令并回车。text> /initOpenCode 会扫描你的项目文件结构，并在项目根目录创建一个名为
AGENTS.md的文件。
✅ 验证：
在你的项目目录中，你应该能看到一个新文件 AGENTS.md。打开它，你会看到 OpenCode 自动生成的对项目结构和技术的描述。
⚠️ 重要提示：请将 AGENTS.md 文件提交到 Git 仓库中。这能确保你和你的团队成员，以及未来的 OpenCode 会话，都能共享这个项目上下文。
第 4 步：开始使用 - 提问与添加功能
🎯 目标：掌握与 OpenCode 交互的两种核心方式：提问和下达任务。
4.1 提问：理解代码
📝 操作：
在 OpenCode 的输入框中，你可以像问同事一样提问。使用 @ 符号可以快速搜索并引用项目中的文件。
> 请解释一下 @src/utils/helpers.ts 文件中的 `formatDate` 函数是如何工作的？✅ 验证：
OpenCode 会读取该文件，并为你生成一段详细的解释，包括函数接受什么参数，返回什么结果，以及内部逻辑。
4.2 添加功能：先计划，后执行
这是一个更强大的功能。我们建议先让 AI “制定计划”，确认无误后再让它“动手”。
步骤 A：切换到计划模式
在输入框中，按
Tab键。你会看到界面右下角的模式指示器从“构建”变为“计划”。输入你的功能需求：
text> 我想为这个项目添加一个“深色模式”切换功能。请先制定一个计划，告诉我需要修改哪些文件，以及如何实现。按回车发送。OpenCode 不会修改任何文件，只会输出一个详细的实施方案。
步骤 B：审查并迭代计划
仔细阅读 OpenCode 给出的计划。如果你觉得某个地方需要调整，可以直接在聊天中反馈：
> 计划看起来不错，但我不想用 CSS 变量，我想用 Tailwind 的 `dark:` 前缀来实现。请更新计划。步骤 C：切换到构建模式并执行
当对计划满意后，再次按 Tab 键，将模式切换回“构建”。然后输入：
> 好的，请按计划开始实施。OpenCode 会开始读取、创建和修改你的代码文件。
✅ 验证：
OpenCode 会在终端中实时显示它正在修改哪些文件以及修改的内容。修改完成后，你可以手动检查代码，或直接运行项目来测试新功能。
进阶技巧（可选）
掌握基础后，你可以尝试：
直接修改：对于简单的任务，可以跳过“计划模式”，直接让 AI 修改。
text> 请将 @config.js 文件中的 `port` 值从 8080 改为 3000。撤销修改：如果 AI 做错了，输入
/undo命令即可撤销上一步的所有修改。可以多次/undo撤销多步操作。/redo可以重做。分享对话：输入
/share命令，OpenCode 会生成一个当前对话的链接并复制到剪贴板，你可以分享给同事。
常见问题 (FAQ)
Q1: 安装时提示 Permission denied 怎么办？A: 在 macOS/Linux 上，可以在命令前加 sudo 来获取管理员权限，例如 sudo curl -fsSL https://opencode.ai/install | bash。在 Windows 上，请以管理员身份运行终端。
Q2: /connect 时粘贴不了 API 密钥？A: 在大多数终端中，右键点击可以粘贴，或者使用快捷键 Ctrl+Shift+V（Windows/Linux）或 Cmd+V（macOS）。注意粘贴时可能不会显示字符，这是安全设计，直接回车即可。
Q3: OpenCode 修改了我不希望它修改的文件怎么办？A: 立即使用 /undo 命令。建议在进行重大修改前，先用 Git 提交当前代码，这样即使 /undo 也解决不了，也可以轻松回退。
总结
恭喜你完成了本教程！🎉
回顾一下我们今天学到的核心内容：
- 安装与配置：学会了用一行命令安装 OpenCode，并配置了 API 密钥。
- 项目初始化：通过
/init命令让 AI 理解项目结构，这是高效协作的基础。 - 交互模式：掌握了“提问模式”用于理解代码，以及“计划+构建模式”用于安全地添加新功能。
- 控制与分享：学会了使用
/undo撤销错误操作，以及用/share分享对话。
下一步
如果你想继续深入，建议学习：
- 📖 [个性化配置教程]: 学习如何更换主题、自定义快捷键、配置代码格式化工具，让 OpenCode 更符合你的习惯。
- 📖 [自定义命令教程]: 学习如何创建你自己的快捷命令，进一步提高效率。
💡 练习任务：找一个你正在做的项目，用
/init初始化它，然后尝试让它为你代码中的一个复杂函数编写单元测试。