LowHow 文档

中文

English

中文

English

深色模式

OpenCode 安装与首次安全运行实战教程：从零开始用AI理解代码 ​

📚 分类: AI 编程工具 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Linux / Windows (WSL2), 终端, Git

你将学到什么 ​

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

  • [ ] 安装并启动 OpenCode 终端界面 (TUI)
  • [ ] 连接一个 AI 模型（如 OpenAI、Anthropic）
  • [ ] 对项目执行一次安全的只读任务
  • [ ] 理解 OpenCode 的核心概念：@ 文件引用、! shell 命令、/ 命令
  • [ ] 掌握在真实项目中使用 OpenCode 的安全底线

最终效果 ​

你将在自己的终端中启动 OpenCode，让它读取你项目中的一个文件并解释其功能，全程不修改任何代码。你会看到一个交互式的终端界面，你可以像和同事对话一样，通过自然语言指挥 AI 助手理解你的代码库。

前置准备 ​

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

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

1. 获取 API Key ​

OpenCode 本身不包含模型，你需要一个第三方模型的 API Key。以下是两个常用选择：

💡 提示: 如果你没有付费 API Key，OpenCode 也支持本地模型（如 Ollama），但本教程以云端模型为例。

✅ 验证: 确保你已复制好 API Key（以 sk- 开头的一串字符）。

第 1 步：安装 OpenCode ​

🎯 目标：在你的系统中安装 OpenCode 命令行工具，并验证安装成功。

📝 操作：

bash
# 使用 npm 全局安装 OpenCode
$ npm install -g @opencode/cli

# 验证安装：查看版本号
$ opencode --version

✅ 验证： 如果看到类似以下输出，说明安装成功：

text
v0.7.2

⚠️ 常见错误：

  • EACCES: permission denied: 权限不足。在 macOS/Linux 上，尝试 sudo npm install -g @opencode/cli。在 Windows 上，以管理员身份运行终端。
  • command not found: opencode: npm 全局安装路径未加入 PATH。解决方案：
    bash
    # 查看 npm 全局安装路径
$ npm config get prefix
# 如果输出是 /usr/local，则执行：
$ echo 'export PATH=$PATH:/usr/local/bin' >> ~/.zshrc
$ source ~/.zshrc

🤔 为什么要全局安装？ 全局安装 (-g) 让 opencode 命令在任何目录下都可执行，就像 git 或 node 一样。如果只在某个项目下安装，你每次都要用 npx opencode 来启动。

第 2 步：配置模型连接（Provider） ​

🎯 目标：告诉 OpenCode 使用哪个 AI 模型以及你的 API Key。

📝 操作：

bash
# 启动 OpenCode 的交互式配置向导
$ opencode init

你会看到终端中出现一个交互式界面。按以下步骤操作：

  1. 选择 Provider（模型提供商）：
    • 如果你使用 OpenAI，选择 openai
    • 如果你使用 Anthropic，选择 anthropic
    • 按 ↑/↓ 键选择，按 Enter 确认
  2. 输入你的 API Key：
    • 粘贴你之前复制的 Key（粘贴时可能不会显示，这是正常的）
    • 按 Enter 确认
  3. 选择 Model（模型）：
    • OpenAI: 推荐 gpt-4o 或 gpt-4o-mini
    • Anthropic: 推荐 claude-3-5-sonnet-20241022
  4. 配置保存路径：直接按 Enter 使用默认路径 ~/.opencode/config.json

✅ 验证： 配置完成后，查看配置文件是否生成：

bash
$ cat ~/.opencode/config.json

你应该能看到类似这样的输出（API Key 会被隐藏或加密显示）：

json
{
  "providers": {
    "openai": {
      "apiKey": "sk-...",
      "model": "gpt-4o"
    }
  }
}

💡 提示: ~/.opencode/config.json 是全局配置文件，影响你所有项目中使用 OpenCode 的行为。

⚠️ 常见错误：

  • 配置向导卡住: 按 Ctrl+C 退出，然后手动创建配置文件：
    bash
    $ mkdir -p ~/.opencode
$ echo '{"providers":{"openai":{"apiKey":"你的API_KEY","model":"gpt-4o"}}}' > ~/.opencode/config.json

第 3 步：进入项目并启动 TUI ​

🎯 目标：进入一个你想让 OpenCode 理解的项目，并启动交互式终端界面 (TUI)。

📝 操作：

bash
# 进入你的项目目录（这里以你的项目为例）
$ cd /path/to/your/project

# 启动 OpenCode 的 TUI 模式
$ opencode

✅ 验证： 启动后，你的终端会变成类似这样的界面：

text
┌─────────────────────────────────────────────────────┐
│  OpenCode v0.7.2                                    │
│  Model: gpt-4o (openai)                             │
│  Working directory: /path/to/your/project           │
├─────────────────────────────────────────────────────┤
│                                                     │
│  > _                                                │
│                                                     │
│  [输入你的指令...]                                   │
│                                                     │
│  @file   引用文件    !shell   执行命令               │
│  /command 命令      Ctrl+L  清屏                    │
└─────────────────────────────────────────────────────┘

💡 提示:

  • 按 Ctrl+L 可以清屏
  • 按 Ctrl+C 可以退出 TUI
  • 如果只想运行一次性命令，可以使用 opencode "你的指令"（非交互模式）

第 4 步：执行第一次只读任务 ​

🎯 目标：让 OpenCode 读取项目中的一个文件并解释其功能，全程不修改任何代码。这是最安全的第一次任务。

📝 操作：

在 TUI 的 > 提示符后，输入以下指令：

text
> @src/index.js 请解释这个文件的主要功能，列出它导出了哪些函数或类，以及每个的作用。不要修改任何代码。

这里 @src/index.js 是文件引用语法，告诉 OpenCode 关注哪个文件。请将 src/index.js 替换为你项目中实际存在的文件路径。

✅ 验证： OpenCode 应该返回类似这样的回答（以 Node.js 项目为例）：

text
文件 `src/index.js` 是一个 Express 服务器入口文件，主要功能是：

1. **导入依赖**：引入了 `express`、`cors` 和 `dotenv` 等库
2. **配置中间件**：启用了 CORS 和 JSON 解析
3. **定义路由**：导入了 `./routes` 中的路由模块
4. **启动服务器**：监听 3000 端口

导出的内容：无直接导出，该文件是应用的启动点。

💡 为什么这个任务安全？

  • 我们没有要求它修改任何文件
  • @ 引用是只读的，OpenCode 只会读取文件内容
  • 我们明确指令"不要修改任何代码"

⚠️ 常见错误：

  • 文件路径错误: 如果 OpenCode 说找不到文件，使用 !ls 命令列出当前目录的文件结构：
    text
    > !ls -R
    这会执行 shell 命令 ls -R，让你确认正确的文件路径。

第 5 步：探索核心交互语法 ​

🎯 目标：掌握 TUI 中的三个核心交互方式，让和 OpenCode 的协作更高效。

📝 操作：

5.1 @ 文件引用 ​

在指令中引用文件或目录，让 OpenCode 关注特定上下文：

text
> @src/ 请总结这个目录下所有文件的功能
> @package.json 这个项目的依赖有哪些？版本号是多少？

5.2 ! Shell 命令 ​

在指令中直接执行终端命令，查看结果：

text
> !git log --oneline -5  显示最近5次提交
> !node -v               查看 Node.js 版本
> !pwd                   查看当前工作目录

5.3 / 命令 ​

使用 OpenCode 内置命令：

text
> /help      显示所有可用命令
> /clear     清空当前会话历史
> /status    显示当前配置状态（模型、文件数等）
> /session   管理会话（保存、加载、分享）

✅ 验证： 尝试执行以下指令序列，确认每个都能正常工作：

text
> !ls -la                    # 查看项目文件
> @README.md 请总结这个文件  # 读取并解释 README
> /status                   # 查看当前状态

🤔 为什么要用这些语法？

  • @ 让 OpenCode 聚焦于特定文件，避免它"忘记"上下文
  • ! 让 OpenCode 能查看实时状态（如当前 git 分支、最近日志）
  • / 命令让你控制 OpenCode 本身的行为，而不是操作你的项目

进阶技巧（可选） ​

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

  1. 对话式调试: 让 OpenCode 分析一个 bug，但只给解释，不改代码：

    text
    > @src/error.js 这段代码可能有 bug，请分析逻辑并指出问题，但不要修改文件。

  2. 生成代码计划: 让 OpenCode 写出修改方案，你手动实施：

    text
    > @src/ 我想添加一个用户登录功能，请给出需要修改哪些文件、每个文件怎么改的详细计划，不要实际修改。

  3. 使用 /session 保存进度: 当你进行复杂对话时，用 /session save 项目分析 保存当前会话，下次用 /session load 项目分析 恢复。

常见问题 (FAQ) ​

Q1: 启动时显示 Error: No provider configured 怎么办？A: 说明你没有完成第 2 步的配置。运行 opencode init 或手动创建 ~/.opencode/config.json 文件。

Q2: 提示 Rate limit exceeded 是什么意思？A: 你的 API Key 请求频率过高。等待 1 分钟后重试，或检查你的 API 套餐是否有限制。

Q3: 如何切换到不同的模型？A: 在 TUI 中使用命令：

text
> /model gpt-4o-mini

或修改配置文件 ~/.opencode/config.json。

Q4: OpenCode 和 Claude Code / Codex 有什么区别？A: OpenCode 是开源、终端优先、多模型兼容的工具。它不绑定特定模型，支持自定义配置规则、技能和工具，适合深度集成到开发工作流中。

Q5: 可以同时配置多个 Provider 吗？A: 可以。在 ~/.opencode/config.json 中，providers 字段可以包含多个条目，如 openai 和 anthropic，在 TUI 中使用 /model 切换。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 安装与配置: 通过 npm install -g @opencode/cli 安装，用 opencode init 配置模型连接
  2. 启动 TUI: 在项目目录运行 opencode 进入交互模式
  3. 安全第一: 第一次任务只读，不修改代码；后续操作也遵循低风险顺序
  4. 核心语法: @ 引用文件、! 执行 shell 命令、/ 使用内置命令
  5. 安全底线: 涉及密钥、支付、数据删除、发布部署时必须人工确认

© 2026 LowHow