LowHow 文档

中文

English

中文

English

深色模式

OpenCode AI 编码助手安装与使用教程：从零开始配置与实战 ​

📚 分类: 开发工具 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 现代操作系统 (Windows/macOS/Linux)，现代终端模拟器

你将学到什么 ​

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

  • [ ] 在本地环境中成功安装 OpenCode
  • [ ] 配置 OpenCode 连接到 AI 模型提供商
  • [ ] 在一个项目中初始化 OpenCode 的配置文件
  • [ ] 使用 OpenCode 完成提问、添加功能、修改代码等基础操作

最终效果 ​

你将拥有一个可以直接在终端里使用的 AI 编码助手。你可以在项目目录中运行 opencode 命令，通过自然语言与它对话，让它帮你理解代码、编写新功能、或者修改现有文件。

前置准备 ​

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

检查项要求验证命令
终端模拟器现代终端 (如 WezTerm, Alacritty, iTerm2, Windows Terminal)直接打开你的终端
API 密钥你想要使用的 LLM 提供商 (如 OpenAI, Anthropic) 的 API 密钥登录你的 LLM 提供商账户查看

1. 安装 OpenCode ​

打开你的终端，使用以下任一方式安装。我们推荐使用安装脚本，因为它最简单。

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

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

✅ 验证：脚本执行完毕后，在终端输入 opencode --version，如果看到类似 opencode version x.x.x 的输出，说明安装成功。

方式二：使用 Node.js 包管理器

如果你已经安装了 Node.js，可以选择以下任一方式：

bash
# 使用 npm
$ npm install -g opencode-ai

# 或者使用 pnpm
$ pnpm install -g opencode-ai

# 或者使用 yarn
$ yarn global add opencode-ai

✅ 验证：运行 opencode --version 检查是否安装成功。

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

bash
$ brew install anomalyco/tap/opencode

✅ 验证：运行 opencode --version 检查是否安装成功。

方式四 (Arch Linux)：使用 pacman

bash
$ sudo pacman -S opencode

✅ 验证：运行 opencode --version 检查是否安装成功。

方式五 (Windows)：使用包管理器

推荐先安装 WSL（Windows Subsystem for Linux），然后在 WSL 中运行安装脚本以获得最佳体验。

在 Windows 的 PowerShell 或 CMD 中，你也可以使用以下方式：

bash
# 使用 Chocolatey
$ choco install opencode

# 使用 Scoop
$ scoop install opencode

✅ 验证：运行 opencode --version 检查是否安装成功。

💡 提示：如果上述方式都不可行，你还可以从 OpenCode Releases 页面 直接下载适用于你操作系统的二进制文件。

第 1 步：配置 API 密钥 ​

🎯 目标：让 OpenCode 知道使用哪个 AI 模型，以及如何验证你的身份。

📝 操作：

  1. 选择一个提供商：如果你是第一次使用，推荐使用 OpenCode Zen。这是一个由 OpenCode 团队精选并经过测试的模型集合，使用起来非常方便。
  2. 获取 API 密钥：
    • 在终端中运行 opencode 命令（这会在当前目录启动 TUI）。
    • 在 TUI 中，输入 /connect 命令并按回车。
    • 从列表中选择 opencode 作为提供商。
    • 系统会提示你访问 opencode.ai/auth。
    • 在浏览器中打开该链接，登录或注册，然后复制你的 API 密钥。
  3. 粘贴 API 密钥：回到终端，将复制的 API 密钥粘贴到提示符处，然后按回车。

✅ 验证： 如果配置成功，你会在 TUI 界面中看到连接成功的提示，并且可以开始与 AI 对话。

🤔 为什么要这样做？/connect 命令是 OpenCode 的配置入口，它引导你完成 API 密钥的设置。API 密钥是你的身份凭证，AI 提供商通过它来识别你的账户并允许你使用其服务。

⚠️ 注意：

  • 如果你选择其他提供商（如 OpenAI、Anthropic），你需要从相应平台获取 API 密钥，然后在 /connect 时选择对应的提供商并粘贴密钥。
  • API 密钥是敏感信息，请勿分享给他人，也不要将其提交到版本控制系统中。

第 2 步：初始化项目 ​

🎯 目标：让 OpenCode 了解你的项目结构和编码规范。

📝 操作：

  1. 首先，导航到你想要使用 OpenCode 的项目目录：
bash
$ cd /path/to/your/project
  1. 在项目根目录下启动 OpenCode：
bash
$ opencode
  1. 在 OpenCode 的 TUI 界面中，输入 /init 命令并按回车。

✅ 验证： OpenCode 会分析你的项目，并在项目根目录下创建一个名为 AGENTS.md 的文件。你会看到类似 "AGENTS.md file created" 的提示。

💡 提示：建议将 AGENTS.md 文件提交到 Git 仓库。它包含了项目的上下文信息，可以帮助 OpenCode 更好地理解你的代码。

第 3 步：开始使用 OpenCode ​

🎯 目标：通过几个实际场景，体验 OpenCode 的核心功能。

📝 操作：

现在，你已经准备好使用 OpenCode 了。在 TUI 界面中，你可以像跟同事聊天一样，用自然语言向它提问或发出指令。

场景一：提问与理解代码 ​

  • 操作：在输入框中输入以下内容，然后按回车：

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

    💡 提示：输入 @ 符号可以模糊搜索并引用项目中的文件。

  • 验证：OpenCode 会读取你指定的文件，并解释其中的认证逻辑。

场景二：添加新功能（推荐先计划） ​

  • 操作：

    1. 按下 Tab 键，切换到 计划模式。你会看到右下角的模式指示器变为 "Plan"。

    2. 输入你的功能需求，例如：

      When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.

    3. OpenCode 会生成一个实现计划，而不是直接修改代码。

    4. 你可以对计划提出反馈，或者拖拽图片到终端提供设计参考。

    5. 当你对计划满意后，再次按下 Tab 键切换回 构建模式。

    6. 输入 Sounds good! Go ahead and make the changes. 让 OpenCode 开始实施。

  • 验证：OpenCode 会按照计划修改你的代码。

场景三：直接修改代码 ​

  • 操作：对于简单的修改，你可以直接发出指令，无需先制定计划。

    We need to add authentication to the /settings route. Take a look at how this is
handled in the /notes route in @packages/functions/src/notes.ts and implement
the same logic in @packages/functions/src/settings.ts

  • 验证：OpenCode 会读取你提供的参考文件，并在目标文件中实现相同的逻辑。

场景四：撤销修改 ​

  • 操作：如果你对 OpenCode 的修改不满意，可以使用 /undo 命令来撤销。

    /undo

  • 验证：OpenCode 会撤销最近一次修改，并重新显示你之前的消息，方便你调整提示词后重试。

    💡 提示：你可以多次使用 /undo 撤销多次修改，也可以使用 /redo 重做。

场景五：分享对话 ​

  • 操作：如果你想将当前对话分享给团队成员，可以使用 /share 命令。

    /share

  • 验证：OpenCode 会生成当前对话的链接并复制到剪贴板。你可以将链接分享给其他人。

    ⚠️ 注意：对话默认不会被分享，只有你主动执行 /share 命令后才会生成链接。

进阶技巧（可选） ​

掌握基础操作后，你可以进一步个性化你的 OpenCode：

  1. 选择主题：在 TUI 中，你可以切换到深色或浅色主题。
  2. 自定义快捷键：你可以修改 OpenCode 的快捷键，使其更符合你的使用习惯。
  3. 配置格式化工具：OpenCode 可以集成你的代码格式化工具，确保生成的代码风格统一。
  4. 创建自定义命令：你可以创建一些常用的提示词模板作为自定义命令，方便快速调用。

常见问题 (FAQ) ​

Q1: 安装脚本执行失败怎么办？A: 可能是网络问题或权限问题。你可以尝试使用其他安装方式（如 npm），或者在命令前加 sudo（macOS/Linux）。如果问题持续，请检查你的系统是否满足前置条件。

Q2: 运行 opencode 后，提示找不到命令？A: 这说明 OpenCode 没有安装成功，或者安装路径没有被添加到系统的 PATH 环境变量中。请重新运行安装命令，或者检查你的 PATH 变量。

Q3: 如何修改已配置的 API 密钥？A: 在 TUI 中再次运行 /connect 命令，选择你的提供商并粘贴新的密钥即可覆盖旧的配置。

Q4: AGENTS.md 文件是干什么的？A: 它是 OpenCode 的项目配置文件，包含了项目的语言、框架、编码规范等信息。OpenCode 通过它来更好地理解你的项目，从而提供更准确的帮助。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安装：通过多种方式在你的系统上安装 OpenCode。
  2. 配置：使用 /connect 命令配置 API 密钥，连接 AI 模型提供商。
  3. 初始化：使用 /init 命令让 OpenCode 了解你的项目。
  4. 使用：掌握了提问、添加功能、直接修改、撤销修改和分享对话等核心交互方式。

© 2026 LowHow