LowHow 文档

中文

English

中文

English

深色模式

OpenCode AI 编程助手安装配置与实战入门教程 ​

📚 分类: AI 编程工具 / 开发环境 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Linux / Windows (WSL2)，现代终端模拟器（如 WezTerm, iTerm2）

你将学到什么 ​

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

  • [ ] 在本地安装并配置 OpenCode AI 编程助手
  • [ ] 连接一个 AI 模型提供商（如 OpenCode Zen）
  • [ ] 在真实的 Git 项目中初始化并运行 OpenCode
  • [ ] 执行安全的“只读”和“只写”任务，理解其核心工作流
  • [ ] 掌握撤销 (/undo) 和分享 (/share) 等关键命令

最终效果 ​

你将在一个真实的项目目录中，成功启动 OpenCode 的终端界面（TUI），并向它下达一个“只读”指令。OpenCode 将分析你的项目结构并给出报告，而不会修改任何文件。你将亲眼见证一个 AI 编程助手如何在你的控制下安全地工作。

前置准备 ​

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

检查项要求验证命令
现代终端WezTerm, Alacritty, Ghostty, Kitty, iTerm2 等echo $TERM (应输出 xterm-256color 或类似值)
Git任何版本git --version
网络连接能正常访问 opencode.ai 等网站无
LLM API Key一个有效的 API 密钥或账户将在第 3 步获取

1. 准备一个真实项目 ​

为了获得最佳体验，请在一个真实的 Git 项目目录中操作。如果你没有现成的项目，可以创建一个简单的测试项目。

bash
# 创建一个测试项目目录
$ mkdir ~/my-opencode-test && cd ~/my-opencode-test

# 将其初始化为 Git 仓库（OpenCode 需要）
$ git init

# 创建一个简单的文件
$ echo "# My OpenCode Test Project" > README.md
$ echo "console.log('Hello, OpenCode!');" > index.js

# 提交初始代码
$ git add .
$ git commit -m "Initial commit"

✅ 验证：执行 ls -la 应该能看到 README.md、index.js 和 .git 目录。

第 1 步：安装 OpenCode ​

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

💡 提示：官方推荐使用安装脚本，这是最直接的方式。如果你偏好包管理器，也可以选择 brew、npm 或 pacman 等方式。

📝 操作：

打开你的终端，执行以下命令：

bash
# 使用官方安装脚本（推荐）
$ curl -fsSL https://opencode.ai/install | bash

或者，如果你使用 Homebrew (macOS/Linux)：

bash
$ brew install anomalyco/tap/opencode

或者，如果你熟悉 Node.js 环境：

bash
$ npm install -g opencode-ai

✅ 验证：

安装完成后，验证命令是否可用：

bash
$ opencode --help

你应该看到 OpenCode 的帮助信息，列出所有可用的子命令（如 auth， run， serve 等）。

⚠️ 常见错误：

  • command not found: opencode：说明安装路径没有添加到系统的 PATH 环境变量中。
    • 解决方案：关闭并重新打开终端，或者运行 source ~/.bashrc (或 ~/.zshrc)。如果问题依旧，尝试找到安装位置（通常是 /usr/local/bin），并用完整路径执行 /usr/local/bin/opencode --help。

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

🎯 目标：将 OpenCode 与一个 AI 模型（如 GPT-4）连接起来。这是它“思考”和“行动”的大脑。

📝 操作：

OpenCode 需要一个 AI 模型来驱动。我们以官方推荐的 OpenCode Zen 为例。

  1. 启动 TUI 并进入连接界面：

    bash
    $ opencode

    在 TUI 启动后，输入斜杠命令：

    text
    /connect

  2. 选择并配置 Provider： 在出现的界面中，选择 OpenCode Zen。系统会提示你访问一个网址来完成授权。

  3. 完成授权： 在浏览器中打开 https://opencode.ai/auth（或提示的网址），登录你的账户，添加账单信息，并复制系统生成的 API Key。

  4. 粘贴 API Key： 回到终端，按照提示粘贴你复制的 API Key。

🤔 为什么要这样做？/connect 命令是 OpenCode 的“安全凭据入口”。你在这里输入的 API Key 会被安全地存储在系统的凭据管理器中，永远不会写入到你的项目文件中。这避免了将敏感信息意外提交到 Git 仓库的风险。

✅ 验证：

连接成功后，TUI 界面应该会显示一个成功的提示。你也可以在终端中直接查看凭据：

bash
$ opencode auth list

这个命令会列出所有已配置的 Provider 及其状态。

⚠️ 常见错误：

  • 连接失败：不要怀疑 OpenCode 坏了。先检查：
    • API Key 是否有效且已激活？
    • 账户账单信息是否已正确添加？
    • 你的网络是否能正常访问 opencode.ai？
    • 你是否在公司内网，需要配置代理？

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

🎯 目标：让 OpenCode 理解你的项目结构和规则。

📝 操作：

  1. 确保你已进入之前创建的测试项目目录：

    bash
    $ cd ~/my-opencode-test

  2. 启动 OpenCode：

    bash
    $ opencode

  3. 在 TUI 中，执行初始化命令：

    text
    /init

OpenCode 会分析你的项目（读取 .gitignore， package.json 等文件），并在项目根目录生成一个名为 AGENTS.md 的文件。这个文件是 OpenCode 的“项目上下文说明书”，告诉 AI 你的项目结构、编码规范、测试命令等关键信息。

⚠️ 重要：/init 生成的只是初稿。在提交 AGENTS.md 到 Git 之前，你必须人工检查并修改它，特别是：

  • 测试命令：确保 npm test 或 pytest 等命令是正确的。
  • 敏感目录：明确指定 node_modules、build、dist 等目录不允许 AI 修改。
  • 不可修改的文件列表：列出任何你不想让 AI 触碰的文件。

✅ 验证：

检查项目根目录是否生成了新文件：

bash
$ ls -la

你应该能看到一个名为 AGENTS.md 的文件。用文本编辑器打开它，看看里面是否包含了你项目的描述。

第 4 步：执行你的第一个任务（只读） ​

🎯 目标：验证 OpenCode 是否能正确理解你的项目，而不修改任何文件。这是建立信任的第一步。

📝 操作：

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

text
先快速阅读这个储存库的目录结构，不要修改文件。
请按这四点输出：
1. 项目的主要技术栈和语言。
2. 核心的目录结构和它们的作用。
3. 你非常有把握的结论。
4. 你现在还不确定、需要我确认的问题。

💡 提示：这个提示词设计得非常巧妙。它同时做了三件事：

  1. 限制动作：明确命令 AI “不要修改文件”。
  2. 验证上下文：看它是否真的理解了项目。
  3. 暴露不确定性：要求它说出自己不确定的地方，避免它“胡编乱造”。

✅ 验证：

你应该看到 OpenCode 开始分析项目，并输出一个结构化的报告，列出项目的技术栈、目录作用和它不确定的地方。关键验证点是，你的项目文件（README.md， index.js）没有任何变化。

⚠️ 常见错误：

  • AI 开始修改文件：如果第一轮只读任务 AI 就开始创建或修改文件，请立即停止。这说明你的提示词不够严谨，或者 AGENTS.md 中的规则没有正确约束 AI。检查你的提示词是否包含了“不要修改文件”的指令。

第 5 步：执行一个低风险写入任务 ​

🎯 目标：让 OpenCode 在严格限制下修改一个文件，并验证修改结果。

📝 操作：

在只读任务稳定后，尝试一个低风险的写入任务。

text
只修改 README.md 中的内容，将标题从 '# My OpenCode Test Project' 改为 '# My First OpenCode Project'。
不要修改其他文件。
改完后，先解释你的修改，再告诉我建议执行什么检查命令。

✅ 验证：

合格的输出应该满足以下几点：

  1. 只修改了你指定的文件：用 git diff 命令检查，确认只修改了 README.md。
    bash
    $ git diff
  2. 解释了修改内容：AI 会告诉你它做了什么。
  3. 给出了验证命令：AI 会建议你运行 cat README.md 来查看修改。
  4. 不会自作主张：AI 不会自动执行 git add， git commit 或 git push。

🤔 为什么要这样做？ 这种“先计划，再执行”的模式是安全使用 AI 编程助手的核心。如果任务复杂，你可以在 TUI 中按 Tab 键切换到 Plan mode，让 AI 只输出计划；确认计划无误后，再按 Tab 回到 Build mode 执行。

第 6 步：学习如何撤销 ​

🎯 目标：掌握撤销 (/undo) 和重做 (/redo) 命令，这是安全操作的“后悔药”。

📝 操作：

在 TUI 中，直接输入以下命令：

text
/undo

这个命令会撤销当前会话中 OpenCode 所做的所有修改。如果你撤销错了，可以输入：

text
/redo

来重做刚刚撤销的修改。

✅ 验证：

在执行第 5 步的写入任务后，输入 /undo，然后用 git diff 检查，你会发现 README.md 的修改被撤销了，文件恢复到了修改前的状态。

⚠️ 注意： /undo 和 /redo 非常强大，但它们只适用于当前会话内的修改。对于涉及数据库迁移、外部服务调用、文件删除等高风险操作，仍然需要你事先仔细审查 AI 的计划。

进阶技巧（可选） ​

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

  1. 使用 /share 分享会话：

    text
    /share

    这会生成一个分享链接。在分享前，务必检查会话中是否包含 API Key、敏感路径、客户信息等机密数据。

  2. 个性化配置： 在 ~/.config/opencode/ 目录下，你可以配置主题、快捷键、自定义命令 (commands) 等，让 OpenCode 更符合你的习惯。

常见问题 (FAQ) ​

Q1: 安装脚本执行失败，报网络错误？A: 请检查你的网络连接。如果在国内，可能需要配置代理。也可以尝试使用 npm 或 brew 等备用安装方式。

Q2: 执行 /init 后，AGENTS.md 文件内容不准确？A: 这是正常的。/init 生成的只是初稿。你必须手动编辑 AGENTS.md，修正测试命令、添加禁止修改的目录和文件列表，使其符合你的项目实际情况。

Q3: AI 开始修改我没有指定的文件，怎么办？A: 立即使用 /undo 撤销所有修改。然后检查你的提示词是否足够清晰（例如，加上“只修改 README.md”）。同时，检查 AGENTS.md 中的规则是否明确禁止了修改其他文件。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安全第一：通过 /connect 安全地管理 API Key，而不是写在项目文件里。
  2. 建立上下文：通过 /init 生成 AGENTS.md，让 AI 理解项目规则。
  3. 渐进式信任：先做“只读”任务，再做“低风险写入”任务，逐步验证 AI 的能力。
  4. 随时可撤销：掌握 /undo 和 /redo，为你的操作提供安全保障。

© 2026 LowHow