❯OpenCode中文站

入门教程

开始使用 OpenCode。

OpenCode↗ 是一个开源的 AI 编程代理。它提供终端界面（TUI）、桌面应用和 IDE 扩展等多种使用方式。

让我们开始吧。

# 准备工作#

在使用 OpenCode 之前，你需要准备好想要使用的 LLM 提供商的 API 密钥。

# 安装#

OpenCode 提供桌面应用和命令行两种安装方式。

## 桌面应用 (推荐)#

对于大多数用户，我们推荐使用 OpenCode Desktop。它提供了完整的 AI 编程体验。

你可以从 下载页面↗ 获取适用于 macOS、Windows 和 Linux 的安装包。

macOS 用户也可以使用 Homebrew 安装：

bash
brew install --cask opencode-desktop

## 命令行 (Hacker)#

如果你更喜欢在终端中工作，或者需要将其集成到现有工作流中，可以使用命令行版本。

终端要求

要在终端中使用 OpenCode，你需要一个现代终端模拟器，例如：

安装脚本

最简单的安装方式是使用安装脚本：

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

你也可以使用以下命令安装：

## 使用 Node.js#

bash
1# npm
2npm install -g opencode-ai
3
4# bun
5bun install -g opencode-ai
6
7# pnpm
8pnpm install -g opencode-ai
9
10# yarn
11yarn global add opencode-ai

## 使用 Homebrew（macOS 和 Linux）#

bash
brew install anomalyco/tap/opencode

根据官方安装文档↗（本小节核验于 2026-10-06），推荐使用 OpenCode 自维护的 tap，以更及时地获得新版本。brew install opencode 仍是有效方式，但其 formula 由 Homebrew 团队维护，更新可能较慢。这是文档核对，未执行安装测试；分平台步骤见安装教程。

## 使用 Paru（Arch Linux）#

bash
paru -S opencode-bin

## Windows#

推荐使用 WSL (Windows Subsystem for Linux) 运行 OpenCode 以获得最佳体验。

bash
1# 使用 Chocolatey
2choco install opencode
3
4# 使用 Scoop
5scoop bucket add extras
6scoop install extras/opencode
7
8# 使用 NPM
9npm install -g opencode-ai

## 使用 Mise#

bash
mise use -g github:anomalyco/opencode

## 使用 Docker#

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

你也可以从 Releases↗ 页面下载二进制文件。

# 配置#

使用 OpenCode，你可以通过配置 API 密钥来使用任何 LLM 提供商。

如果你是 LLM 提供商的新手，我们推荐使用 OpenCode Zen。这是一个经过 OpenCode 团队测试和验证的模型精选列表。

  1. 在 TUI 中运行 /connect 命令，选择 opencode，然后访问 opencode.ai/auth↗。

    /connect

  2. 登录，添加付款信息，然后复制你的 API 密钥。

  3. 粘贴你的 API 密钥。

    ┌ API key
│
└ enter

你也可以选择其他提供商。了解更多。

# 初始化#

配置好提供商后，你可以导航到想要工作的项目目录。

bash
cd /path/to/project

然后运行 OpenCode：

bash
opencode

接下来，运行以下命令初始化项目：

/init

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

提示： 你应该将项目的 AGENTS.md 文件提交到 Git。这有助于 OpenCode 理解项目结构和使用的编码模式。

# 使用方法#

现在你已经准备好使用 OpenCode 来处理你的项目了。随时向它提问！

如果你是 AI 编程代理的新手，以下是一些可能有帮助的示例。

## 提问#

你可以让 OpenCode 向你解释代码库。

提示： 使用 @ 键可以模糊搜索项目中的文件。

@packages/functions/src/api/index.ts 中的身份验证是如何处理的？

如果代码库中有你没有参与开发的部分，这会很有帮助。

## 添加功能#

你可以让 OpenCode 为你的项目添加新功能。不过，我们首先建议让它创建一个计划。

  1. 创建计划

    OpenCode 有一个计划模式，它会禁用修改功能，转而建议如何实现该功能。

    使用 Tab 键切换到计划模式。你会在右下角看到一个指示器。

    <TAB>

    现在让我们描述我们想要它做什么：

    当用户删除一个笔记时，我们希望在数据库中将其标记为已删除。
然后创建一个屏幕，显示所有最近删除的笔记。
在这个屏幕上，用户可以恢复笔记或永久删除它。

    你需要给 OpenCode 足够的细节来理解你的需求。就像和团队中的初级开发者交流一样会很有帮助。

    提示： 给 OpenCode 充足的上下文和示例，帮助它理解你想要什么。

  2. 迭代计划

    一旦它给你一个计划，你可以给它反馈或添加更多细节。

    我们希望使用我之前用过的设计来设计这个新屏幕。
[图片 #1] 看看这张图片并以此作为参考。

    提示： 将图片拖放到终端中以将其添加到提示中。

    OpenCode 可以扫描你提供的任何图片并将它们添加到提示中。你可以通过将图片拖放到终端中来实现。

  3. 构建功能

    当你对计划感到满意时，再次按 Tab 键切换回构建模式。

    <TAB>

    然后让它进行更改：

    听起来不错！继续进行更改吧。

## 进行更改#

对于更直接的更改，你可以直接让 OpenCode 构建它，而不必先审查计划。

我们需要为 /settings 路由添加身份验证。看看这在
@packages/functions/src/notes.ts 的 /notes 路由中是如何处理的，
并在 @packages/functions/src/settings.ts 中实现相同的逻辑。

确保你提供足够的细节，以便 OpenCode 做出正确的更改。

## 撤销更改#

假设你让 OpenCode 进行了一些更改：

你能重构 @packages/functions/src/api/index.ts 中的函数吗？

但你意识到这不是你想要的。你可以撤销更改，使用 /undo 命令：

/undo

OpenCode 现在将恢复你所做的更改，并再次显示你原来的消息：

你能重构 @packages/functions/src/api/index.ts 中的函数吗？

从这里你可以调整提示并让 OpenCode 再试一次。

提示： 你可以多次运行 /undo 来撤销多个更改。

或者你可以重做更改，使用 /redo 命令：

/redo

# 分享#

你与 OpenCode 的对话可以与团队分享。

/share

这将创建一个指向当前对话的链接并将其复制到剪贴板。

注意： 对话默认不会被分享。

这是一个与 OpenCode 的示例对话↗。

# 自定义#

就是这样！你现在是使用 OpenCode 的专家了。

为了让它成为你自己的，我们建议选择一个主题、自定义快捷键、配置代码格式化工具、创建自定义命令，或者探索 OpenCode 配置。

相关文档

配置使用 OpenCode JSON 配置文件提供商配置 LLM 提供商和 API 密钥网络配置代理和自定义证书