LowHow 文档

中文

English

中文

English

深色模式

OpenCode 实战教程：从零搭建你的 AI 编程助手 ​

📚 分类: AI 编程工具入门 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: 任意操作系统（Windows / macOS / Linux），可联网 🌐 原文来源: OpenCode 中文教程

你将学到什么 ​

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

  • [ ] 理解 OpenCode 的“先规划，后执行”核心工作流（Plan & Build 双模式）
  • [ ] 在你的电脑上成功安装并配置 OpenCode
  • [ ] 创建第一个项目，并体验 AI 智能体（Agent）的初步交互
  • [ ] 了解如何通过 AGENTS.md 文件让 AI 更懂你的项目

最终效果 ​

你将在终端中运行 OpenCode，并向它提出一个简单的编程需求。OpenCode 会先给出一个详细的修改计划（Plan 模式），在你确认后，它会自动完成代码的编写和修改（Build 模式）。你将亲身体验到“AI 先思考，后动手”的全新编程流程。

前置准备 ​

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

检查项要求版本验证命令
Node.js≥ 18.0node -v
npm≥ 8.0npm -v
Git≥ 2.30git --version

1. 安装 Node.js 和 npm ​

OpenCode 是基于 Node.js 构建的。如果你还没有安装，请前往 Node.js 官网 下载并安装最新的 LTS（长期支持）版本。安装完成后，打开终端（Terminal）验证。

bash
# 验证 Node.js 安装
$ node -v
# 预期输出：v18.x.x 或更高版本

# 验证 npm 安装
$ npm -v
# 预期输出：8.x.x 或更高版本

✅ 验证：如果看到类似 v18.17.0 和 9.6.7 的输出，说明 Node.js 和 npm 环境准备就绪。

💡 提示：如果你使用的是 Windows，建议使用 PowerShell 或 Git Bash 作为终端，以获得更好的体验。

第 1 步：安装 OpenCode ​

🎯 目标：在全局环境中安装 OpenCode，使其成为一个可在终端中直接调用的命令。

📝 操作：

bash
# 使用 npm 全局安装 opencode 包
$ npm install -g opencode

🤔 为什么要这样做？-g 参数代表 global（全局）。这意味着安装完成后，你可以在任何目录下，通过在终端输入 opencode 命令来启动它，而不需要每次都进入它的安装目录。

✅ 验证：

bash
# 验证 OpenCode 是否安装成功
$ opencode --version
# 预期输出：类似 v0.1.0 的版本号

⚠️ 常见错误： 如果在 npm install -g 时遇到 EACCES 权限错误（通常在 macOS/Linux 上），说明你没有全局写入的权限。

  • 解决方案 1（推荐）：使用 Node.js 版本管理器（如 nvm）来安装 Node.js，这样会自动处理权限问题。
  • 解决方案 2（临时）：在命令前加上 sudo：
    bash
    $ sudo npm install -g opencode

第 2 步：创建你的第一个项目 ​

🎯 目标：创建一个空的目录作为你的项目文件夹，并初始化一个 Node.js 项目，为后续的 AI 编程做准备。

📝 操作：

bash
# 1. 创建一个名为 my-first-opencode-project 的文件夹，并进入该文件夹
$ mkdir my-first-opencode-project && cd my-first-opencode-project

# 2. 初始化一个 Node.js 项目（-y 参数表示使用所有默认配置，避免手动输入）
$ npm init -y

✅ 验证： 执行 npm init -y 后，终端会显示类似以下输出：

text
Wrote to /path/to/your/project/my-first-opencode-project/package.json:

{
  "name": "my-first-opencode-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

这说明你的项目已经初始化成功，package.json 文件已经创建好了。

第 3 步：启动 OpenCode 并体验 AI 交互 ​

🎯 目标：启动 OpenCode，让它理解你的项目，并引导你完成第一个 AI 辅助编程任务。

📝 操作：

  1. 启动 OpenCode： 在你的项目根目录（my-first-opencode-project）下，运行以下命令：

    bash
    $ opencode

    首次启动时，OpenCode 可能会询问你关于 API Key 或本地模型的一些配置。请根据终端提示进行设置。为了快速体验，你可以先选择使用免费或内置的模型（如果有的话）。具体配置可以参考 OpenCode 的官方文档。

  2. 输入你的第一个指令： 当 OpenCode 启动并进入交互界面后，输入以下指令并回车：

    创建一个 index.js 文件，内容是一个用 Express.js 构建的简单 Web 服务器，它监听 3000 端口，当访问根路径 "/" 时，返回 "Hello from OpenCode!"。

    🤔 发生了什么？ OpenCode 会进入 Plan 模式。它不会立刻修改你的代码，而是会先分析你的需求，并给出一个详细的修改计划，例如：

      1. 安装 express 依赖包。
      1. 创建 index.js 文件。
      1. 在 index.js 中编写服务器代码。

  3. 确认计划并执行： 仔细阅读 OpenCode 给出的计划。如果计划符合你的预期，输入 y 或 yes 来确认。

    ✅ 验证： OpenCode 会进入 Build 模式，并开始自动执行计划中的步骤。你将在终端中看到它正在安装 express 包，然后创建和编辑 index.js 文件。整个过程完成后，你会看到类似 任务完成 的提示。

    bash
    # 在项目目录下，查看新创建的文件
$ ls -l
# 你应该能看到 index.js 文件
    javascript
    // 使用 cat 命令查看文件内容
$ cat index.js
// 预期输出：
const express = require('express');
const app = express();

app.get('/', (req, res) => {
  res.send('Hello from OpenCode!');
});

app.listen(3000, () => {
  console.log('Server is running on http://localhost:3000');
});

    💡 验证最终效果：在终端运行 node index.js，然后打开浏览器访问 http://localhost:3000，你应该能看到页面上显示“Hello from OpenCode!”。

第 4 步：引入智能体（Agent）规范 ​

🎯 目标：创建一个 AGENTS.md 文件，让 OpenCode 记住你的项目偏好，例如编码风格或特定的技术栈。

📝 操作：

  1. 创建 AGENTS.md 文件： 在项目根目录下，创建一个名为 AGENTS.md 的文件。

  2. 写入规范： 使用文本编辑器打开 AGENTS.md，将以下内容写入并保存：

    markdown
    # 项目规范：My First OpenCode Project

## 技术栈
- 运行时：Node.js
- 框架：Express.js

## 编码风格
- 使用 ES6 模块语法（`const`, `let`, 箭头函数）
- 所有 API 端点返回 JSON 格式数据
- 错误处理使用 `try...catch` 块

## 项目目标
这是一个用于学习 OpenCode 的演示项目。

    🤔 为什么要这样做？AGENTS.md 文件就像一个项目“说明书”。当 OpenCode 读取这个文件后，它就能了解你的项目背景和偏好。在后续的交互中，它会自动遵循这些规范，生成的代码会更符合你的预期，就像一个熟悉你项目的老同事。

  3. 验证效果： 现在，再次启动 OpenCode，并输入一个新的指令：

    添加一个新的 API 端点 /api/time，返回当前服务器时间的 JSON 对象。

    你会发现，OpenCode 这次生成的代码会直接使用 const 和箭头函数，并且返回的是 JSON 格式，因为它已经读取了 AGENTS.md 中的规范。

进阶技巧（可选） ​

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

  1. 使用本地模型：如果你有较强的本地硬件，可以配置 OpenCode 使用 Ollama 等本地大语言模型，实现 100% 离线、隐私安全的 AI 编程。
  2. 集成 MCP 协议：通过 MCP（Model Context Protocol），让 OpenCode 连接到你的数据库、文件系统或 API 网关，实现更强大的自动化能力。

常见问题 (FAQ) ​

Q1: 运行 opencode 后，提示 command not found 怎么办？A: 这说明 OpenCode 没有被正确安装到系统的 PATH 环境变量中。请确保 npm install -g opencode 命令执行成功且没有报错。尝试重新打开一个终端窗口，或者检查 npm 的全局安装目录（通常为 /usr/local/lib/node_modules）是否在 PATH 中。

Q2: 如何修改 AI 模型？A: 在 OpenCode 的配置文件（通常位于 ~/.opencode/config.json 或项目根目录下的 .opencode 文件夹中）中，你可以修改 model 字段来指定不同的 AI 模型。具体支持的模型列表请参考官方文档。

Q3: 如何退出 OpenCode 交互界面？A: 在交互界面中，输入 exit 或 quit，或者直接按下 Ctrl + C 组合键。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安装与配置：学习了如何通过 npm 全局安装 OpenCode，并初始化一个 Node.js 项目。
  2. 核心工作流：体验了 OpenCode 的 Plan → Build 双模式，理解了“AI 先规划，后执行”是提升代码质量和效率的关键。
  3. 智能体（Agent）：学会了如何通过创建 AGENTS.md 文件，为 AI 提供项目上下文和编码规范，让 AI 成为更懂你的“编程伙伴”。

© 2026 LowHow