opencode-map
English
← guides/

opencode 快速上手

入门最后更新: 2026年10月21日

opencode 是一个开源 AI 编码 agent,提供终端界面(TUI)、桌面应用和 IDE 扩展三种形态。本篇走终端路线:安装 → 接入 provider → 初始化项目 → 完成第一次改动。

安装

本篇覆盖 OpenCode 1,即 opencode.ai/docs 文档对应的稳定线。OpenCode 2 已发布(v2 文档)——两代共用 opencode 二进制名、不能并存,用下面的方式安装 v1 可能冲突或覆盖已装的 v2。

推荐官方脚本:

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

包管理器方式:

npm install -g opencode-ai        # Node.js(bun / pnpm / yarn 同理)
brew install anomalyco/tap/opencode  # macOS/Linux——Anomaly tap 更新最快
sudo pacman -S opencode           # Arch Linux(稳定);paru -S opencode-bin 跟 AUR 最新
choco install opencode            # Windows(建议走 WSL);scoop install opencode 亦可
mise use -g github:anomalyco/opencode  # mise
docker run -it --rm ghcr.io/anomalyco/opencode  # 容器

Windows 上官方建议用 WSL 以获得完整功能。也可以直接从 GitHub Releases 下载二进制。

接入 provider

opencode 与供应商无关——通过 models.dev 支持 75+ provider,自带 API key 即可。没有 provider 账号的话,OpenCode Zen 是官方团队测试验证过的精选模型列表,按请求计费走 opencode 账户;也可以看官方的统一订阅 OpenCode Go。

在 TUI 里执行:

/connect

选择 provider(opencode/Zen、Anthropic、OpenAI 等),按提示完成授权并粘贴 API key。

初始化项目

cd /path/to/project
opencode

然后执行:

/init

opencode 会分析项目并在根目录生成 AGENTS.md,描述项目结构与编码约定。建议提交到 Git——它能让之后每次会话都更懂你的代码库。

plan/build 工作流

TUI 有两个模式,用 Tab 切换:

  • Build 模式(默认)——直接改代码。
  • Plan 模式——只读,先给方案,反复打磨后再切回 build 执行。

可靠的首个功能流程:

  1. Tab 进 plan 模式,尽量详细地描述需求(图片可直接拖进终端)。
  2. 对方案迭代反馈。
  3. Tab 回 build 模式:「开始实施」。

prompt 里用 @ 模糊引用文件:@src/api/index.ts 里的鉴权怎么实现的。

撤销、重做

  • /undo 撤销上一次改动并还原你的消息,可连续执行多次。撤销要求项目是一个 Git 仓库。
  • /redo 重做。

延伸阅读