Open Code 文档

主题

首页文档搜索

OpenCode 实战教程：从零搭建你的第一个 AI 编程工作流 ​

📚 分类: AI 编程工具 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Linux / Windows (WSL2)，现代终端 🌐 原文来源: OpenCode 官方文档

你将学到什么 ​

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

  • [ ] 安装并配置 OpenCode，连接一个大型语言模型（LLM）提供商
  • [ ] 在真实项目中初始化 AI 辅助编程上下文，让 AI 理解你的项目
  • [ ] 安全地执行第一次“只读”和“写入”任务，理解 AI agent 的工作边界
  • [ ] 掌握 /undo 和 /redo 命令，学会撤销 AI 的修改
  • [ ] 了解如何安全地分享你的工作会话

最终效果 ​

你将成功在终端里启动 OpenCode，让它读取你的项目结构，并按照你的指示修改一个文件（比如 README.md），且能通过 /undo 命令撤销该修改。整个过程安全可控，你将亲身体验 AI 编程助手的工作模式。

前置准备 ​

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

检查项要求验证命令说明
操作系统macOS / Linux / Windows (WSL2)uname -a (Mac/Linux) 或 wsl -l -v (Windows)OpenCode 依赖 Git 和 Shell，WSL2 能提供最佳体验
现代终端WezTerm / Alacritty / Ghostty / Kitty / iTerm2 等无特定命令这些终端对 TUI 界面、快捷键和图片拖放支持更好
Git≥ 2.30git --version用于版本控制和项目初始化
LLM API Key如 OpenAI, Anthropic 等无特定命令这是 AI 推理的核心，你需要一个有效的 API key 或使用 OpenCode Zen

1. 准备你的 LLM API Key ​

🎯 目标：确保你有一个有效的 API key，这是 AI 编程助手的“大脑”。

📝 操作：

  • 访问你选择的 LLM 提供商官网（如 OpenAI, Anthropic 等）。
  • 注册账号并创建一个 API key。
  • 复制并安全保存你的 API key。

✅ 验证：你已成功生成并复制了一个以 sk- 或类似前缀开头的 API key。

💡 提示：如果你还没有 API key，可以优先选择 OpenCode Zen 服务，它提供了一个开箱即用的支付和管理方案，无需预先准备第三方 key。

第 1 步：安装 OpenCode ​

🎯 目标：在你的电脑上安装好 OpenCode 命令行工具。

📝 操作： 打开你的终端，根据你的系统选择一种安装方式。

方式一：使用官方安装脚本（推荐）

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

方式二：使用 Homebrew (macOS / Linux)

bash
$ brew install anomalyco/tap/opencode

方式三：使用 npm (Node.js 环境)

bash
$ npm install -g opencode-ai

✅ 验证： 安装完成后，在终端输入以下命令，如果能正常显示帮助信息，说明安装成功。

bash
$ opencode --help
# 预期输出：显示 opencode 命令的所有可用选项和子命令

🤔 为什么要这样做？opencode --help 是最快的验证方式，它能确认命令已被正确安装到系统路径中。如果命令找不到，请检查你的 PATH 环境变量。

⚠️ 常见错误： 如果出现 command not found: opencode，请尝试：

bash
$ which opencode
# 查看 opencode 安装在哪里
$ echo $PATH
# 查看你的系统 PATH 是否包含了安装目录

第 2 步：连接模型提供商 ​

🎯 目标：让 OpenCode 能够通过你的 API key 调用 AI 模型。

📝 操作： 进入一个你想进行实验的空目录（或任何目录），然后启动 OpenCode 的 TUI 界面。

bash
$ cd ~/Desktop
$ opencode

在 TUI 界面中，输入斜杠命令：

bash
/connect

系统会引导你选择提供商。你可以：

  1. 选择 OpenCode Zen：按照屏幕上的链接，在浏览器中完成注册和支付，获取 API key 并粘贴回终端。
  2. 选择其他提供商（如 OpenAI）：粘贴你之前准备好的 API key。

✅ 验证： 连接成功后，TUI 界面顶部或状态栏会显示已连接的模型名称。你也可以在终端中使用 CLI 命令验证：

bash
$ opencode auth list
# 预期输出：显示已配置的提供商列表

💡 提示：API key 只会保存在本地的凭据系统中，不会写入你的项目文件。你可以在 AGENTS.md 中写工作流规则，但永远不要写真实的 Key。

第 3 步：在真实项目中初始化 ​

🎯 目标：让 OpenCode 理解你项目的结构和上下文。

📝 操作： 进入一个你真正想用 AI 辅助的项目目录（比如一个你正在开发的网站或脚本）。然后再次启动 OpenCode。

bash
$ cd /path/to/your/real/project
$ opencode

在 TUI 界面中，执行初始化命令：

bash
/init

OpenCode 会分析你的项目，并在项目根目录下生成一个 AGENTS.md 文件。

✅ 验证： 查看项目根目录，你应该能看到一个名为 AGENTS.md 的新文件。用文本编辑器打开它，你会看到类似项目结构、技术栈、测试命令等信息的初稿。

🤔 为什么要这样做？/init 命令创建了一个“项目说明书”，告诉 AI 你的项目是什么、怎么运行、有什么约定。这能极大提高后续 AI 任务的准确性和安全性。

⚠️ 常见错误： /init 生成的只是初稿，在提交到 Git 之前，你必须人工审核并修改它。特别是其中的测试命令、部署命令、以及“哪些文件不能修改”的规则，务必确认无误。

第 4 步：执行第一次只读任务 ​

🎯 目标：在不修改任何文件的前提下，验证 AI 能否正确理解你的项目。

📝 操作： 在 TUI 中，输入以下提示词（Prompt）：

text
先快速阅读这个储存库的目录结构，不要修改档案。
请按这四点输出：
1. 专案类型和主要技术栈。
2. 目录结构概览。
3. 你会优先阅读哪些档案来理解专案。
4. 你现在还不确定、需要我确认的问题。

✅ 验证： AI 应该会输出一个结构化的回答，包含项目类型、技术栈和目录结构。如果它开始修改文件，请立即停止。

💡 提示：要引用特定文件，使用 @ 符号进行模糊搜索，例如：

text
How is authentication handled in @packages/functions/src/api/index.ts

第 5 步：执行第一次写入任务（只改一个文件） ​

🎯 目标：让 AI 执行一个低风险的写入操作，并学会控制修改范围。

📝 操作： 在 TUI 中，输入以下提示词：

text
只修改 README.md 中的安装说明，把命令整理成 macOS、Linux、Windows 三段。
不要修改其他档案。
改完后先解释 diff，再告诉我建议执行什么检查命令。

✅ 验证： 合格的 AI 响应应该满足以下四点：

  1. 只修改了你指定的文件。
  2. 能解释具体 diff（即修改了哪些行）。
  3. 能给出合理的验证命令（如 cat README.md）。
  4. 不会自作主张 commit、push 或部署。

⚠️ 常见错误： 如果任务稍显复杂，或者你不确定 AI 会如何修改，可以先按 Tab 键切换到 Plan mode。此时 AI 只会给出修改计划，不会执行。确认计划无误后，再按 Tab 切回 Build mode 执行。这比事后用 /undo 恢复一堆文件要安全得多。

第 6 步：学会撤销与重做 ​

🎯 目标：掌握撤销和重做功能，这是使用 AI 编程的安全网。

📝 操作： 在上一步修改完 README.md 后，在 TUI 中输入：

bash
/undo

然后，如果你想恢复修改，可以输入：

bash
/redo

✅ 验证： 执行 /undo 后，使用 cat README.md 查看文件，你会发现它恢复到了修改前的状态。执行 /redo 后，修改会再次生效。

💡 提示：/undo 和 /redo 只对当前会话（Session）中 AI 产生的修改有效。它不能替代 Git 的版本控制。对于数据库迁移、部署等高风险操作，仍然要依赖于 Git 进行管理。

第 7 步：分享你的会话（可选） ​

🎯 目标：了解如何安全地分享你的 AI 编程过程。

📝 操作： 在 TUI 中，输入：

bash
/share

OpenCode 会生成一个分享链接。

✅ 验证：你会得到一个类似 https://opencode.ai/share/xxxxx 的链接，可以将其发送给同事。

⚠️ 常见错误： 在分享前，务必确认当前会话中不包含任何敏感信息，例如：

  • API Key 或密码
  • 客户数据或内部路径
  • 未公开的仓库信息或商业策略

对话默认不会自动分享，所以请谨慎操作。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 自定义 Slash 命令：在 AGENTS.md 中定义你自己的快捷命令，比如 /fix-lint 或 /test-module，减少重复输入。
  2. 使用 Rules：创建更精细的规则文件，告诉 AI 在特定情况下该如何行动，例如“永远不要修改 dist/ 或 node_modules/ 目录”。
  3. 探索其他入口：除了 TUI，你还可以使用 opencode run（CLI 模式）或将其集成到 VS Code 等 IDE 中。

常见问题 (FAQ) ​

Q1: 连接模型时失败，显示 Authentication Error 怎么办？A: 首先确认你的 API key 有效且余额充足。其次，检查你的网络代理设置。最后，尝试使用 opencode auth login 重新登录。

Q2: AI 不按我的要求修改文件怎么办？A: 立即使用 /undo 撤销。然后，检查你的提示词是否足够清晰和具体。尝试使用 Plan mode，让 AI 先给出计划，你确认后再执行。

Q3: 如何让 AI 理解一个非常大的项目？A: 使用 @ 符号引用关键文件，并在 AGENTS.md 中清晰描述项目的核心架构、模块职责和关键文件路径。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安全第一：通过 /init、只读任务、单文件修改和 /undo，构建了一个安全闭环，确保 AI 的行为可控。
  2. 渐进式学习：从安装、连接到初始化，再到执行任务，每一步都验证了结果，并理解了背后的原理。
  3. 掌握核心命令：熟练掌握了 /connect、/init、/undo、/redo 和 /share 等关键命令。

下一步 ​

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

  • 📖 CLI 入口：深入学习 opencode run、opencode auth 等命令，实现脚本化操作。
  • 📖 TUI 工作流：探索 @ 文件引用、Shell 命令执行、模式切换等高级功能。
  • 📖 Rules 与 AGENTS.md：学习如何编写更精细的规则，将项目知识沉淀下来，让 AI 成为你的“资深团队成员”。

💡 练习任务：尝试修改本教程的 AGENTS.md，添加一条规则：“在修改任何文件前，必须先输出修改计划”。然后让 AI 修改一个文件，观察它是否遵守了规则。

yaml

Open Code 文档社区

© 2026 Open Code. All rights reserved.