OpenCode – 开源编程代理。

OpenCode 使用指南：安装、配置与快速上手

OpenCode 是一款运行在终端中的 AI 编程助手，支持接入多种大语言模型（LLM），帮助开发者理解代码、制定开发计划、编写功能、重构代码以及管理项目。

前提条件

在终端中使用 OpenCode 之前，你需要准备：

终端模拟器

推荐使用以下现代终端工具：

• WezTerm（跨平台）
• Alacritty（跨平台）
• Ghostty（Linux 和 macOS）
• Kitty（Linux 和 macOS）

API 密钥

准备好你计划使用的 LLM 提供商 API Key。

如果是首次使用，推荐使用 OpenCode Zen，这是 OpenCode 官方测试和验证过的模型集合。

安装 OpenCode

使用安装脚本（推荐）

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

使用 NPM 安装

npm install -g opencode-ai

使用 Homebrew 安装（macOS / Linux）

brew install anomalyco/tap/opencode

推荐使用 OpenCode 官方 Tap，可获得最新版本。Homebrew 官方仓库中的版本更新频率较低。

Arch Linux 安装

稳定版：

sudo pacman -S opencode

最新版（AUR）：

paru -S opencode-bin

Windows 安装

推荐：WSL

官方推荐使用 Windows Subsystem for Linux（WSL）。

优势：

• 性能更好
• 支持全部 OpenCode 功能
• 开发体验更完整

Chocolatey 安装

choco install opencode

Scoop 安装

scoop install opencode

NPM 安装

npm install -g opencode-ai

Mise 安装

mise use -g github:anomalyco/opencode

Docker 运行

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

Windows 下通过 Bun 安装的支持仍在开发中。

你也可以直接从 Releases 页面下载预编译二进制文件。

配置 OpenCode

启动 OpenCode 后运行：

/connect

选择：

opencode

然后访问：

opencode.ai/auth

完成以下步骤：

1. 登录账户
2. 添加账单信息
3. 创建 API Key
4. 复制 API Key
5. 粘贴到 OpenCode

示例：

┌ API key
│
│
└ enter

你也可以连接其他 LLM 提供商。

初始化项目

进入项目目录：

cd /path/to/project

启动 OpenCode：

opencode

然后执行：

/ init

（实际命令为 /init）

OpenCode 会自动：

• 分析项目结构
• 理解代码组织方式
• 在项目根目录生成 AGENTS.md 文件

建议将 AGENTS.md 提交到 Git 仓库：

git add AGENTS.md
git commit -m "Add OpenCode project configuration"

这样可以帮助 OpenCode 更准确地理解项目结构和开发规范。

使用 OpenCode

代码库问答

你可以直接询问代码相关问题：

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

文件搜索

输入：

@

即可模糊搜索项目文件。

当面对陌生代码时，这个功能非常有帮助。

使用计划模式开发功能

对于较大的功能开发，建议先让 OpenCode 制定方案。

进入计划模式

按下：

TAB

切换到 Plan Mode。

右下角会显示当前模式。

描述需求

例如：

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.

建议提供尽可能详细的业务需求。

可以把 OpenCode 当作团队中的初级开发工程师来沟通。

优化计划

如果 OpenCode 给出的方案需要调整，可以继续补充说明：

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.

图片分析

支持直接拖放图片到终端：

• PNG
• JPG
• JPEG
• WebP

OpenCode 会自动分析图片内容并纳入上下文。

开始开发

当你确认计划没有问题后：

再次按下：

TAB

返回 Build Mode。

然后输入：

Sounds good! Go ahead and make the changes.

OpenCode 将开始编写代码并修改项目。

直接修改代码

对于简单需求，可以跳过计划阶段。

示例：

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

OpenCode 将：

• 回滚代码修改
• 恢复之前状态
• 重新显示原始提示词

例如：

Can you refactor the function in
@packages/functions/src/api/index.ts?

随后你可以修改提示词重新尝试。

重做修改

如果撤销后又想恢复：

/redo

即可重新应用之前的修改。

分享对话

执行：

/share

OpenCode 会：

• 生成当前会话链接
• 自动复制到剪贴板

方便与团队成员共享讨论内容。

默认情况下，对话不会自动公开分享。

个性化配置

熟悉 OpenCode 后，你还可以进一步自定义使用体验：

• 更换主题（Themes）
• 自定义快捷键（Keybindings）
• 配置代码格式化工具（Formatters）
• 创建自定义命令（Custom Commands）
• 调整 OpenCode 配置文件

通过这些设置，你可以打造更符合个人开发习惯的 AI 编程环境。

总结

OpenCode 是一款面向开发者的终端 AI 编程助手，支持代码理解、功能规划、自动开发、代码重构、版本回滚以及团队协作分享等功能。通过接入多种 LLM 模型，开发者可以在本地终端中获得类似 AI Pair Programming 的开发体验，大幅提升开发效率和代码质量。

Zen 为您提供一组精选的 AI 模型，这些模型经过 OpenCode 专门针对编程代理的测试和基准测试。无需担心不同提供商之间不稳定的性能和质量，直接使用行之有效的验证模型。

拥有超过 颗 GitHub Star， 位贡献者，以及超过 次提交，OpenCode 每月被超过 名开发者使用并信赖。