LowHow 文档

中文

English

中文

English

深色模式

OpenCode 实战教程：15分钟跑通AI编程安全闭环 ​

📚 分类: AI 编程工具 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Linux / Windows (WSL)

你将学到什么 ​

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

  • [ ] 在终端中安装并启动 OpenCode
  • [ ] 成功连接一个 AI 模型提供商
  • [ ] 让 OpenCode 安全地读取并分析一个 Git 项目
  • [ ] 执行一次受控的、低风险的代码修改
  • [ ] 使用 /undo 命令撤销不满意的修改

最终效果 ​

你将在一个真实的 Git 仓库里，让 OpenCode 完成一次“只读分析”和一次“限定范围的文件修改”。你会看到一个 AI 编程助手在你的控制下，清晰地理解项目结构，并按照你的指令精确地修改代码，而不会越界。

前置准备 ​

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

检查项要求版本验证命令
现代终端WezTerm / Alacritty / Ghostty / Kitty / iTerm2打开你的终端即可
Git≥ 2.30git --version
网络连接能够访问 opencode.ai 及你选择的模型提供商无

1. 准备：获取 LLM 模型 API 密钥 ​

OpenCode 本身不提供推理能力，它需要连接一个外部的 AI 模型。你需要提前准备好一个 API 密钥。

  • 推荐方式：访问你选择的模型提供商（如 OpenAI、Anthropic 或其他兼容服务）的官网，注册并创建一个 API Key。
  • 与 OpenCode 的关系：API Key 是 OpenCode 与模型通信的“密码”。它会被安全地保存在你的本地凭据系统中，不会写入你的项目文件。

第 1 步：安装 OpenCode ​

🎯 目标：在你的开发机器上成功安装 OpenCode，并能在终端中运行它。

📝 操作：

打开你的终端，根据你的系统选择以下一种方式进行安装。

macOS / Linux (推荐): 使用官方安装脚本，这是最直接的方式。

bash
# 运行官方安装脚本
$ curl -fsSL https://opencode.ai/install | bash

macOS (Homebrew 用户): 如果你使用 Homebrew，也可以使用官方 tap。

bash
$ brew install anomalyco/tap/opencode

Node.js 环境: 如果你有 Node.js 环境，可以通过 npm 全局安装。

bash
$ npm install -g opencode-ai

Windows: 强烈建议先安装 WSL（Windows Subsystem for Linux），然后在 WSL 环境中使用上述 macOS/Linux 的安装方式。这能避免很多与 shell、Git 和文件权限相关的兼容性问题。

✅ 验证： 安装完成后，在终端输入以下命令，检查是否安装成功。

bash
$ opencode --help

💡 预期输出：你应该能看到 OpenCode 的帮助信息，列出了各种可用命令和选项。

⚠️ 常见错误：如果提示 command not found，说明安装路径没有在系统的 PATH 环境变量中。可以尝试以下命令查找安装位置：

bash
$ which opencode
$ echo $PATH

如果 which 找不到，可能需要重新打开终端或手动将安装路径添加到 ~/.bashrc 或 ~/.zshrc 文件中。

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

🎯 目标：让 OpenCode 通过你的 API 密钥连接到 AI 模型，使其具备推理能力。

📝 操作：

首先，在终端中输入 opencode 并回车，启动 OpenCode 的 TUI（文本用户界面）。

bash
# 启动 OpenCode
$ opencode

进入 TUI 后，输入以下命令来连接模型提供商：

bash
/connect

你会看到一个列表，让你选择提供商。对于第一次尝试，选择 OpenCode Zen 是一个不错的选择。按照屏幕上的提示，用浏览器打开 opencode.ai/auth，登录你的账户，添加账单信息并复制 API Key。然后，将复制的 Key 粘贴回终端。

🤔 为什么要用 /connect？/connect 是专为 TUI 设计的交互式命令，它引导你完成整个认证流程，非常适合第一次上手。你也可以在终端中使用 opencode auth login 命令来管理凭据，但 /connect 更直观。

✅ 验证： 连接成功后，TUI 界面应该会显示已连接的模型信息。此时，你可以尝试输入一个简单的对话，比如“你好”，如果模型能正常回复，说明连接成功。

⚠️ 常见错误：

  • 连接失败：不要立刻怀疑 OpenCode 坏了。请按以下顺序排查：
    1. API Key 是否正确：检查是否复制了完整的 Key，没有多余空格。
    2. 账单状态：确认你的模型提供商账户没有欠费。
    3. 网络代理：如果你使用代理，确保它没有干扰 OpenCode 的网络连接。
    4. 提供商服务状态：检查提供商的服务是否正常。

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

🎯 目标：让 OpenCode 理解你当前项目的结构、技术栈和约定，为后续的智能操作打下基础。

📝 操作：

  1. 首先，退出当前的 opencode 会话（按 Ctrl + C 或 :q 退出）。
  2. 进入一个你真正想要使用 OpenCode 的 Git 项目目录。
  3. 再次启动 opencode。
bash
# 进入你的项目目录（请替换为你的实际路径）
$ cd /path/to/your/project

# 启动 OpenCode
$ opencode
  1. 在 TUI 中，输入以下命令：
bash
/init

OpenCode 会开始分析你的项目，并生成一个名为 AGENTS.md 的文件。这个文件位于项目根目录，记录了项目结构、包管理器、测试命令、编码约定等关键信息。

🤔 为什么要做 /init？/init 创建了一个“项目上下文说明书”，让 OpenCode 在后续任务中能理解项目的基本规则，避免“乱猜”。这个文件应该被提交到 Git 仓库，成为团队共享的知识库。

✅ 验证： 执行完 /init 后，在你的项目根目录下应该能看到一个新文件 AGENTS.md。你可以用 cat AGENTS.md 命令查看它的内容。它应该包含类似“项目使用 Python 和 pip”、“测试命令是 pytest”之类的描述。

⚠️ 重要提醒： /init 生成的是初稿。在提交到 Git 之前，你必须人工检查并修改它。确保其中的测试命令、部署命令、敏感目录（如包含密码的 config 文件夹）和“哪些文件绝对不能改”的规则是正确的。

第 4 步：第一轮只读分析 ​

🎯 目标：验证 OpenCode 能否正确理解项目结构，并严格遵循“只读不写”的指令。

📝 操作：

在 TUI 中，输入以下提示词。这个提示词专门设计来测试 OpenCode 的理解能力和纪律性。

请快速阅读这个仓库的目录结构，不要修改任何文件。
请按这四点输出：
1.  这个项目的主要功能是什么？
2.  项目使用了哪些主要的技术栈？
3.  你会优先阅读哪些文件来理解项目？
4.  你现在还不确定、需要我确认的问题。

✅ 验证： 一个合格的回复应该：

  • 清晰地回答了上述 4 个问题。
  • 引用了具体的文件或目录，例如“根据 src/main.py 和 requirements.txt，我认为...”。
  • 完全没有任何“正在修改文件”或“创建新文件”的迹象。

💡 提示：如果你想引用特定文件，可以在提示词中使用 @ 符号进行模糊搜索，例如：How is authentication handled in @packages/functions/src/api/index.ts。

⚠️ 如果它开始改文件： 如果你发现 OpenCode 在执行这个只读任务时尝试修改文件，请立即停止。这说明你需要检查：

  • 你的提示词是否足够清晰（是否明确写了“不要修改文件”）？
  • 当前模式是否为 Build 模式（默认）？对于复杂任务，可以先按 Tab 键切换到 Plan 模式，让它只给出计划。

第 5 步：第一轮受控写入 ​

🎯 目标：让 OpenCode 执行一次低风险的、范围明确的文件修改，并学习如何审查它的改动。

📝 操作：

在完成只读分析后，我们来尝试一个简单的写入任务。这个任务风险极低，因为修改的是文档文件。

只修改 README.md 中的安装说明部分，把命令整理成 macOS、Linux、Windows 三段。
不要修改其他任何文件。
改完后，先解释你具体修改了哪里（diff），再告诉我建议运行什么检查命令（比如 cat README.md）来验证。

✅ 验证： 一个合格的回复应该满足以下四点：

  1. 只修改了你指定的文件：README.md。
  2. 能解释具体的 diff：例如“我在 ## Installation 章节下，将原来的单行命令替换为了三个独立的代码块，分别对应 macOS、Linux 和 Windows。”
  3. 能给出合理的验证命令：例如“建议运行 cat README.md 查看修改后的内容。”
  4. 不会自作主张：不会擅自 git commit、git push 或运行部署命令。

🤔 为什么要先解释 diff？ 这让你有机会在代码被“提交”或“执行”之前，审查 AI 的意图。这是安全使用 AI 编程助手的核心原则。

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

🎯 目标：掌握 /undo 命令，让你在 AI 犯错时能轻松回退，增强使用信心。

📝 操作：

OpenCode 支持撤销当前会话中产生的所有文件修改。在 TUI 中，输入以下命令：

bash
/undo

如果你撤销错了，还可以重做：

bash
/redo

✅ 验证： 执行 /undo 后，检查刚才被修改的 README.md 文件，它应该恢复到了修改前的状态。

⚠️ 能撤销不等于可以随便改： /undo 只适用于当前会话中的文件修改。它不能撤销以下操作：

  • 数据库迁移
  • 外部服务的 API 调用
  • 已发布的部署
  • 删除文件（某些情况下）
  • 批量格式化

对于这些高风险操作，仍然需要先让 OpenCode 给出计划，审查通过后再执行。

进阶技巧（可选） ​

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

  1. 分享会话：在 TUI 中输入 /share 可以生成一个分享链接。注意：分享前务必检查会话中是否包含 API Key、密码、客户数据等敏感信息。
  2. 个性化配置：在 ~/.config/opencode/ 或项目根目录下，你可以配置：
    • 主题和快捷键：让 TUI 更符合你的喜好。
    • rules：在 AGENTS.md 之外，添加更细致的项目规则。
    • commands：将常用的复杂提示词变成简单的斜杠命令，比如 /fix-lint。

常见问题 (FAQ) ​

Q1: 安装脚本卡住或报错怎么办？A: 检查网络连接，并确保 curl 和 bash 命令可用。如果反复失败，可以尝试使用包管理器（如 brew 或 npm）安装。

Q2: 如何切换不同的 AI 模型？A: 在 TUI 中再次输入 /connect，可以选择不同的提供商或模型。你也可以在配置文件中进行更详细的设置。

Q3: 我可以不使用 TUI，只用命令行吗？A: 当然可以。OpenCode 提供了丰富的 CLI 命令，如 opencode run 用于直接执行任务。本教程专注于 TUI 入门，CLI 的使用是下一步学习的内容。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安装与连接：掌握了 OpenCode 的安装和与 AI 模型的连接方法。
  2. 项目初始化：学会了用 /init 让 AI 理解你的项目上下文。
  3. 安全闭环：体验了“只读分析 → 受控写入 → 撤销回退”的安全工作流。
  4. 核心原则：理解了“先验证，再信任；先计划，再执行”是安全使用 AI 编程助手的关键。

© 2026 LowHow