LowHow 文档中心

中文

English

中文

English

深色模式

OpenCode AI 编码助手 ​

📚 分类: AI 开发工具 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Windows / Linux，终端（Terminal） 🌐 原文来源: OpenCode 官网

你将学到什么 ​

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

  • [ ] 在本地成功安装 OpenCode 命令行工具
  • [ ] 配置不同的 AI 模型提供商（如 GPT-4、Gemini）
  • [ ] 区分并使用 OpenCode 的“计划模式”和“构建模式”
  • [ ] 掌握常用命令，并利用 AGENTS.md 文件提升 AI 协作效率
  • [ ] 通过实际案例，体验 AI 辅助编码的完整工作流

最终效果 ​

你将拥有一个配置好的、可直接在项目终端中使用的 AI 编码助手。你只需输入自然语言指令，它就能帮你理解代码、添加功能、修复 Bug，甚至进行代码重构。你将看到一个带有输入框和聊天记录的终端界面。

前置准备 ​

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

检查项要求版本验证命令
终端任意打开即可
Git≥ 2.0git --version
Node.js (可选)≥ 18.0node -v

💡 提示：没有 Node.js 也没关系，我们主要使用一键安装脚本。

第 1 步：安装 OpenCode ​

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

📝 操作：

推荐使用一键安装脚本，这是最快、最稳定的方式。

打开你的终端，粘贴并运行以下命令：

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

🤔 为什么要这样做？curl 命令会从 OpenCode 官网下载一个安装脚本，并通过管道 | 传递给 bash 来执行。脚本会自动检测你的操作系统并完成安装，无需手动处理复杂的依赖。

✅ 验证：

安装完成后，关闭并重新打开终端，输入以下命令验证：

bash
$ opencode --version

你应该会看到类似 opencode version x.x.x 的输出。如果没有，请尝试以下备用安装方法：

  • macOS (Homebrew):
    bash
    $ brew install opencode
  • Windows (Scoop):
    powershell
    $ scoop install opencode
  • npm (全局安装):
    bash
    $ npm install -g opencode-ai@latest

⚠️ 常见错误：

  • 权限问题: 如果 npm 安装报错 EACCES，在命令前加 sudo（Mac/Linux）或以管理员身份运行终端（Windows）。
  • 命令未找到: 安装后需要重启终端，或者检查环境变量是否已正确配置。

第 2 步：配置 AI 模型提供商 ​

🎯 目标：选择一个 AI 模型（如 GPT-4、Gemini）并配置 API 密钥，让 OpenCode 拥有“大脑”。

📝 操作：

OpenCode 支持多种 AI 提供商。你需要选择其中一个，并获取相应的 API 密钥。

  1. 获取 API 密钥：

    • OpenAI (GPT-4)：访问 platform.openai.com 注册并创建 API 密钥。
    • Google (Gemini)：访问 aistudio.google.com 获取 API 密钥。
    • 本地模型 (Ollama)：如果你希望完全离线运行，可以安装 Ollama，下载模型后本地运行。

  2. 配置环境变量： 将你的 API 密钥设置为环境变量。打开终端，执行以下命令（将 your-key-here 替换为你的真实密钥）：

    bash
    # 如果你选择 OpenAI
$ export OPENAI_API_KEY="your-key-here"

# 如果你选择 Google Gemini
$ export GEMINI_API_KEY="your-key-here"

    💡 提示：为避免每次打开终端都要重新设置，建议将上面的 export 命令添加到你的 Shell 配置文件（如 ~/.bashrc、~/.zshrc）中。

✅ 验证：

配置完成后，运行 opencode，程序会尝试连接你配置的 AI 提供商。如果没有报错“API Key not found”，说明配置成功。

⚠️ 常见错误：

  • Anthropic (Claude) 被屏蔽：如果你尝试配置 Claude，可能会遇到连接失败的问题。这是因为 Anthropic 在 2026 年 1 月后屏蔽了第三方工具对其 API 的访问。解决方案：请改用 OpenAI 或 Google Gemini 作为替代。

第 3 步：启动 OpenCode 并理解核心概念 ​

🎯 目标：成功启动 OpenCode，并理解其最核心的两种工作模式。

📝 操作：

  1. 启动： 在你的项目目录中，直接输入 opencode 并回车。

    bash
    $ cd your-project-directory
$ opencode

    你将看到一个漂亮的终端用户界面（TUI）被加载出来。

  2. 理解两种模式： OpenCode 有两大核心模式，通过键盘的 Tab 键进行切换。

    • 🧠 计划模式 (Plan Mode)：

      • 状态：只读。它不会修改你任何文件。
      • 用途：用于分析代码库、理解架构、制定实现方案。在动手写代码前，先用它来思考。
      • 适用场景：“这个项目的认证流程是怎样的？”、“我打算添加一个用户头像上传功能，请帮我规划一下步骤。”

    • 🔨 构建模式 (Build Mode)：

      • 状态：读写。它可以创建、修改和删除文件。
      • 用途：执行实际的编码任务，如添加功能、修复 Bug、重构代码。
      • 适用场景：“帮我实现上面规划好的用户头像上传功能。”、“修复这个登录页面的样式错误。”

🤔 为什么要这样做？ “先计划，后构建”是一个非常重要的开发习惯。计划模式让你在投入精力编码前，先和 AI 对齐思路，避免做无用功。构建模式则专注于执行，效率更高。

✅ 验证： 启动后，你会看到一个输入提示符。尝试输入 /help 并按回车，应该能看到所有可用命令的列表。

第 4 步：创建 AGENTS.md 文件，提升协作效率 ​

🎯 目标：创建一个项目配置文件，让 OpenCode 更好地理解你的项目。

📝 操作：

在项目的根目录下，创建一个名为 AGENTS.md 的文件。这个文件就像一份“项目说明书”，告诉 OpenCode 你的项目背景、技术栈和编码规范。

markdown
# 项目: My Awesome Project

## 技术栈
- 前端: Next.js 14 (App Router)
- 样式: Tailwind CSS
- 后端: Python (FastAPI)
- 数据库: PostgreSQL with SQLAlchemy

## 编码规范
- 前端组件使用函数式组件
- 后端 API 遵循 RESTful 风格
- 所有公共函数必须包含类型注解和文档字符串
- 使用 ESLint 和 Prettier 进行代码格式化

## 项目结构
- `/frontend` - Next.js 前端应用
- `/backend` - FastAPI 后端服务
- `/shared` - 前后端共享的类型定义

🤔 为什么要这样做？ 没有 AGENTS.md，OpenCode 只能通过分析代码文件来猜测你的意图。有了它，AI 就能立刻理解你的项目全貌，给出的代码建议会更符合你的技术栈和规范，质量更高。

✅ 验证： 重启 opencode，然后在计划模式下提问：“请根据 AGENTS.md 描述一下这个项目的技术栈。” AI 应该能准确回答出你文件里写的内容。

第 5 步：实战演练：用 AI 理解代码 ​

🎯 目标：通过一个真实场景，体验 OpenCode 的“计划模式”如何帮助你快速理解一个不熟悉的代码库。

📝 操作：

假设你刚接手一个项目，需要理解其用户登录流程。

  1. 确保你处于 计划模式（按 Tab 键切换到）。

  2. 在输入框中输入以下指令并回车：

    请分析这个项目，并详细解释用户登录的整个流程，包括前端如何提交、后端如何验证、以及 Session/Token 是如何管理的。

  3. OpenCode 会开始分析项目文件，并最终输出一个结构化的解释。

✅ 验证： 你会看到 AI 给出的详细分析，例如：

  • 前端使用 /pages/login.tsx 中的表单，通过 POST /api/auth/login 提交用户名和密码。
  • 后端 auth.py 验证凭据后，生成一个 JWT Token 并返回。
  • 前端将 Token 存储在 localStorage 中，并在后续请求的 Authorization 头中携带。

进阶技巧 ​

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

  1. 非交互模式：用于脚本或自动化任务。
    bash
    $ opencode -p "用 Go 语言写一个简单的 HTTP 服务器，监听 8080 端口，返回 'Hello, World!'"
  2. GitHub 集成：在 Issue 或 PR 的评论中，输入 /opencode 修复这个 Issue 中描述的 Bug，OpenCode 会自动创建一个修复 PR。

常见问题 (FAQ) ​

Q1: 如何撤销 AI 做的修改？A: 在 OpenCode 终端中输入 /undo 命令。

Q2: 如何修改 AI 提供商？A: 你需要创建一个配置文件。在全局路径 ~/.config/opencode/opencode.json 或项目根目录下创建 opencode.json，并按照文档格式指定你想要的模型。

Q3: 报错 EADDRINUSE 是什么意思？A: 这不是 OpenCode 的错误。如果 OpenCode 在本地启动了一个服务（如调试服务器）且端口被占用，会出现此错误。使用 lsof -i :端口号 找到占用进程并关闭它。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安装与配置：掌握了一键安装脚本和 API 密钥的配置方法。
  2. 核心模式：理解了“计划模式”用于分析思考，“构建模式”用于动手编码。
  3. 项目协作：学会了创建 AGENTS.md 文件来提升 AI 的上下文理解能力。
  4. 实战应用：体验了用自然语言让 AI 理解复杂代码库的工作流。

© 2026 LowHow