Open Code 文档

主题

首页文档搜索

OpenCode 实战教程：在终端里玩转 AI 编程助手 ​

📚 分类: AI 工具 / 开发环境配置 ⏱️ 预计耗时: 15 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Linux / Windows (WSL2)

你将学到什么 ​

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

  • [ ] 在终端中安装并初始化 OpenCode
  • [ ] 配置自己的 AI 模型（如 OpenAI、Claude 等）
  • [ ] 通过 TUI（终端界面）与 AI 对话，完成代码生成任务
  • [ ] 理解 OpenCode 的核心架构和工作流程

最终效果 ​

你将能够在自己的终端里，通过一个炫酷的 TUI（Terminal User Interface，终端用户界面）与 AI 助手对话。例如，输入“用 Rust 写一个计算器”，AI 会自动生成代码并保存到本地文件。

前置准备 ​

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

检查项要求版本验证命令
Node.js≥ 18.0node -v
npm / yarn / pnpm / bun任意一个包管理器npm -v
Git≥ 2.30git --version

1. 安装 OpenCode ​

OpenCode 提供多种安装方式，这里我们推荐使用最通用的 npm 进行安装。

bash
# 使用 npm 全局安装 OpenCode
$ npm i -g opencode-ai@latest

✅ 验证：安装完成后，运行以下命令验证是否成功。

bash
$ opencode --version

如果看到类似 1.0.0 的版本号输出，说明安装成功。如果提示 command not found，请检查你的 npm 全局安装路径是否已添加到系统环境变量 PATH 中。

第 1 步：初始化 OpenCode 并配置 AI 模型 ​

🎯 目标：完成 OpenCode 的初始化设置，并配置你的第一个 AI 模型（Provider，即 AI 服务提供商）。

📝 操作：

OpenCode 提供了一个交互式向导来帮助你完成初始配置。

bash
# 启动初始化向导
$ opencode --init

此时，终端会进入一个交互式配置流程。你需要依次完成以下操作：

  1. 选择 AI Provider：根据提示，选择你想使用的 AI 模型提供商。例如，如果你有 OpenAI 的 API Key，就选择 OpenAI；如果有 Anthropic 的，就选择 Anthropic。
  2. 输入 API Key：当提示输入 API Key 时，粘贴你的密钥（输入时不会显示，这是正常的）。
  3. 选择具体模型：向导会列出该 Provider 下可用的模型，选择一个你需要的，例如 gpt-4o 或 claude-3-5-sonnet-20240620。
  4. 完成配置：按照提示完成剩余步骤，向导会自动生成配置文件。

✅ 验证：

配置完成后，OpenCode 会在你的用户目录下生成一个名为 opencode.json 的配置文件。你可以用以下命令检查它是否已生成：

bash
$ cat ~/.opencode/opencode.json

你应该能看到类似下面的内容（具体配置项会有所不同）：

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "apiKey": "sk-...",  // 你的 API Key (已隐藏部分)
      "models": {
        "gpt-4o": {
          "name": "GPT-4o"
        }
      }
    }
  }
}

💡 提示：$schema 字段指向一个 JSON Schema 文件，它可以帮助你的编辑器（如 VS Code）提供自动补全和校验功能。

第 2 步：启动 TUI 与 AI 对话 ​

🎯 目标：启动 OpenCode 的 TUI 界面，发起你的第一次 AI 对话。

📝 操作：

初始化完成后，你就可以直接启动 TUI 了。

bash
# 启动 OpenCode 终端界面
$ opencode

执行命令后，你的终端会变成一个全新的交互界面。这就是 OpenCode 的 TUI。

  1. 你会看到一个输入框，光标在其中闪烁，等待你的指令。

  2. 在输入框中输入你的需求，例如：

    text
    用 Python 写一个函数，可以计算斐波那契数列的第 n 项。

  3. 按下 Enter 键发送消息。

🤔 为什么要这样做？opencode 命令会启动一个 Go 语言编写的高性能 TUI 进程。它负责渲染界面、捕获你的输入，并通过本地 HTTP 服务器与 AI 模型进行通信。整个交互过程完全在终端内完成，无需离开你的开发环境。

✅ 验证：

发送消息后，你会看到：

  1. 输入框上方出现一个“思考中”或类似的指示器。
  2. 几秒后，AI 的回复会以流式（逐字出现）的方式显示在界面上。
  3. 如果 AI 生成了代码，它会以代码块的形式呈现。

💡 提示：TUI 界面支持多会话管理。你可以通过快捷键（通常在界面底部有提示）创建新会话、切换历史会话，就像在浏览器中使用 ChatGPT 一样。

第 3 步：执行更复杂的任务——让 AI 操作文件 ​

🎯 目标：体验 OpenCode 的核心能力——让 AI 不仅能回答问题，还能直接操作你的文件系统。

📝 操作：

OpenCode 的强大之处在于它集成了“工具”。例如，ReadTool 和 WriteTool 允许 AI 读取和写入文件。

  1. 在 TUI 中输入一个更复杂的指令，例如：

    text
    帮我用 Go 语言写一个冒泡排序算法，并将代码保存到当前目录下的 `bubble_sort.go` 文件中。

  2. 发送消息。

✅ 验证：

  1. AI 会先“思考”如何完成这个任务。

  2. 然后，你会看到 TUI 界面上出现类似 [Tool: WriteTool] 或 [正在写入文件...] 的提示。

  3. 任务完成后，AI 会在回复中告诉你文件已生成。

  4. 退出 TUI（通常按 Ctrl+C 或 Esc），检查当前目录：

    bash
    $ ls -l bubble_sort.go

    你应该能看到这个新生成的文件。打开它，里面是完整的、带有注释的 Go 代码。

🤔 为什么要这样做？ 这背后是 OpenCode 的“工具生态”在发挥作用。AI 模型本身不能直接操作文件，但 OpenCode 的 HTTP 服务器提供了一系列标准化的工具接口（如 WriteTool）。AI 模型在生成回复时，可以决定“调用”哪个工具。它的调用请求会通过 HTTP 发送回服务器，服务器再执行真正的文件写入操作。这使得 AI 从一个“聊天机器人”升级为一个“编程助手”。

⚠️ 常见错误： 如果 AI 回复说“我没有权限写入文件”，请检查 OpenCode 的运行目录。它默认会在你启动 opencode 命令的当前工作目录下进行操作。确保你对这个目录有写入权限。

进阶技巧（可选） ​

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

  1. 切换 AI 模型：在 TUI 中，通常可以通过快捷键（如 Ctrl+P）快速切换已配置好的不同 AI 模型，对比它们的输出效果。
  2. 自定义快捷键：修改 ~/.opencode/opencode.json 文件中的 keybinds 字段，将常用操作绑定到你习惯的快捷键上。
  3. 使用 Shell 命令工具：尝试让 AI 帮你执行 Shell 命令，例如“帮我查找当前目录下所有大于 1MB 的文件”。AI 会调用 ShellTool 来执行命令并返回结果。

常见问题 (FAQ) ​

Q1: 安装时报错 EACCES: permission denied 怎么办？A: 这是权限问题。Mac/Linux 用户可以在命令前加 sudo 重试（sudo npm i -g opencode-ai@latest），或者按照 npm 官方文档配置全局安装路径。Windows 用户请以管理员身份运行 PowerShell 或 CMD。

Q2: 启动后 TUI 界面是乱码或显示异常？A: 这通常是因为你的终端字体不支持某些特殊字符。请确保你的终端使用支持 Nerd Font 的字体，例如 JetBrainsMono Nerd Font、FiraCode Nerd Font 等。你可以在 GitHub 上搜索并安装它们。

Q3: 如何修改配置文件 opencode.json？A: 直接用文本编辑器打开 ~/.opencode/opencode.json 文件即可。修改后保存，重新启动 opencode 命令使配置生效。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安装与初始化：通过 npm 安装 OpenCode，并使用 --init 命令快速配置 AI 模型。
  2. TUI 交互：启动 opencode 进入终端界面，与 AI 进行流畅的对话。
  3. 工具集成：体验了 AI 通过 WriteTool 等工具直接操作文件系统的强大功能，理解了其“AI + 工具”的工作范式。

下一步 ​

如果你想继续深入，建议学习：

  • 📖 OpenCode 官方文档：深入了解所有配置项、快捷键和工具 API。
  • 📖 学习配置本地模型：探索如何接入本地运行的 Llama、Mistral 等模型，实现完全离线、私密的 AI 编程体验。

💡 练习任务：尝试让 OpenCode 的 AI 助手帮你重构一段你之前写的代码，或者为你的项目自动生成单元测试。这是巩固知识、体验 AI 编程助力的最佳方式。

yaml

## 相关文档

- [终端 AI 编程实战指南：Claude Code 与 OpenCode 双工具上手](/docs/chu-ci-shi-yong/zhong-duan-ai-bian-cheng-shi-zhan-zhi-nan-claude-code-yu-opencode-shuang-gong-ju-shang-shou.html)
- [OpenCode Zen 实战教程：快速接入精选 AI 模型](/docs/chu-ci-shi-yong/opencode-zen-shi-zhan-jiao-cheng-kuai-su-jie-ru-jing-xuan-ai-mo-xing.html)
- [OpenCode 终端 AI 编程助手 实战教程](/docs/chu-ci-shi-yong/opencode-zhong-duan-ai-bian-cheng-zhu-shou-shi-zhan-jiao-cheng.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.