OpenCode 简介

OpenCode 是一个 开源的 AI 编程代理（AI coding agent）。它可以以 终端界面（terminal-based interface）、桌面应用（desktop app） 或 IDE 扩展（IDE extension） 的形式使用。

OpenCode TUI with the opencode theme

让我们开始吧。

前置条件（Prerequisites）

要在终端中使用 OpenCode，你需要：

1. 一个现代化的终端模拟器（terminal emulator），例如：

2. 你要使用的 LLM 提供商的 API Key

安装（Install）

安装 OpenCode 最简单的方法是使用官方安装脚本。

终端窗口（Terminal window）：

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

你也可以使用以下方式安装：

使用 Node.js

  • npm
  • Bun
  • pnpm
  • Yarn

终端窗口：

  1. npm install -g opencode-ai
  1. bun install -g opencode-ai
  1. pnpm install -g opencode-ai
  1. yarn global add opencode-ai

在 macOS 和 Linux 上使用 Homebrew

终端窗口：

  1. brew install anomalyco/tap/opencode

建议使用 OpenCode tap 获取最新版本。 官方的 brew install opencode formula 由 Homebrew 团队维护，更新频率较低。

在 Arch Linux 上使用 Paru

终端窗口：

  1. paru -S opencode-bin

Windows 安装方式

使用 Chocolatey

  1. choco install opencode

使用 Scoop

  1. scoop bucket add extras
  2. scoop install extras/opencode

使用 NPM

  1. npm install -g opencode-ai

使用 Mise

  1. mise use -g github:anomalyco/opencode

使用 Docker

  1. docker run -it --rm ghcr.io/anomalyco/opencode

目前 Windows 使用 Bun 安装 OpenCode 的支持仍在开发中。

你也可以从 Releases 页面直接下载二进制文件（binary）。

配置（Configure）

OpenCode 支持通过配置 API Key 来使用任意 LLM 提供商。

如果你是第一次使用 LLM 提供商，推荐使用 OpenCode Zen。 这是一个由 OpenCode 团队测试和验证过的模型精选列表（curated list）。

配置步骤

1. 在 TUI 中运行 /connect 命令，选择 opencode，然后访问：

  1. /connect

打开页面： https://opencode.ai/auth

2. 登录账号，填写计费信息（billing details），并复制你的 API Key

3. 粘贴你的 API Key

  1. ┌ API key││└ enter

你也可以选择其他 LLM 提供商。 更多信息请参考：Learn more。

初始化（Initialize）

完成 Provider 配置后，进入你要工作的项目目录。

终端窗口：

  1. cd /path/to/project

启动 OpenCode：

  1. opencode

接着运行初始化命令：

  1. /init

OpenCode 会分析你的项目，并在项目根目录创建一个 AGENTS.md 文件。

💡 提示（Tip）

建议将项目的 AGENTS.md 文件提交到 Git 仓库中。 这可以帮助 OpenCode 更好地理解项目结构和编码风格（coding patterns）。

使用（Usage）

现在你已经可以使用 OpenCode 来协助开发了，可以随时向它提问。

如果你是第一次使用 AI coding agent，下面是一些常见使用示例。

提问（Ask questions）

你可以让 OpenCode 帮你解释代码结构。

💡 提示 使用 @ 键可以对项目文件进行模糊搜索（fuzzy search）。

示例：

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

当你遇到不是自己写的代码时，这个功能特别有用。

添加功能（Add features）

你可以让 OpenCode 为项目添加新功能。推荐先让它生成一个计划（plan）。

1. 创建计划（Create a plan）

OpenCode 提供了 Plan mode，在该模式下不会修改代码，而是给出实现方案。

按下 Tab 键 切换到 Plan mode，右下角会显示当前模式指示。

  1. <TAB>

然后描述你的需求：

  1. 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.

建议像和团队里的初级开发者（junior developer）沟通一样，给出足够清晰的说明。

💡 提示 尽量提供充足的上下文（context）和示例（examples），帮助 OpenCode 理解你的需求。

2. 迭代计划（Iterate on the plan）

当 OpenCode 给出计划后，你可以补充反馈或进一步细化需求。

  1. We'd like to design this new screen using a design I've used before. [Image #1] Take a look at this image and use it as a reference.

💡 提示 你可以将图片直接拖拽到终端中，OpenCode 会自动解析图片并加入 prompt。

3. 构建功能（Build the feature）

确认计划没问题后，再次按下 Tab 键 切换回 Build mode。

  1. <TAB>

然后让它开始修改代码：

  1. Sounds good! Go ahead and make the changes.

直接修改（Make changes）

对于简单需求，可以直接让 OpenCode 修改代码，无需先制定计划。

示例：

  1. 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

请尽量提供充分的细节，避免产生错误修改。

撤销修改（Undo changes）

如果你对 OpenCode 的修改结果不满意，可以使用 /undo 命令撤销。

  1. /undo

OpenCode 会恢复到修改前的状态，并重新显示你的原始指令。

你可以多次执行 /undo 来撤销多步操作。

如果需要恢复撤销的修改，可以使用 /redo 命令：

  1. /redo

分享（Share）

你可以将与 OpenCode 的对话分享给团队成员。

  1. /share

该命令会生成一个链接并复制到剪贴板。

⚠️ 注意 对话默认不会自动分享。

示例对话： https://opencode.ai/s/4XP1fce5

自定义（Customize）

现在你已经可以熟练使用 OpenCode 了 🎉

你可以进一步个性化配置：

  • 选择主题（themes）
  • 自定义快捷键（keybinds）
  • 配置代码格式化工具（code formatters）
  • 创建自定义命令（custom commands）
  • 调整 OpenCode 配置（OpenCode config）