第二章：安装、环境准备与快速上手

本章带你从零完成 OpenCode 的安装、模型接入、项目初始化，并跑通第一个完整会话。完成本章后，你就具备了使用 OpenCode 的最小可用环境。

2.1 环境前提

在终端中使用 OpenCode，建议准备：

1. 一个现代终端模拟器（对 TUI 渲染更友好）：

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

2. 你想使用的 LLM 提供商的 API Key（或使用 OpenCode Zen，或本地模型）。

3. Git：/undo、/redo、会话快照等功能依赖项目是一个 Git 仓库。

Windows 用户强烈建议使用 WSL（Windows Subsystem for Linux），兼容性和性能都更好。

2.2 安装方式

一键安装脚本（最简单）

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

安装脚本会按以下优先级选择安装目录：

1. $OPENCODE_INSTALL_DIR —— 自定义安装目录
2. $XDG_BIN_DIR —— 符合 XDG 规范的路径
3. $HOME/bin —— 标准用户二进制目录（若存在或可创建）
4. $HOME/.opencode/bin —— 默认兜底

# 指定安装目录的例子
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin       curl -fsSL https://opencode.ai/install | bash

包管理器安装

# Node 生态（npm / bun / pnpm / yarn 任选其一）
npm install -g opencode-ai

# macOS / Linux（推荐用官方 tap，更新最及时）
brew install anomalyco/tap/opencode
# 或官方 Homebrew 公式（更新较慢）
brew install opencode

# Windows
scoop install opencode
choco install opencode

# Arch Linux
sudo pacman -S opencode      # 稳定版
paru -S opencode-bin         # AUR 最新版

# 任意系统
mise use -g opencode

# Nix
nix run nixpkgs#opencode

提示：安装前请先卸载 0.1.x 之前的老版本，避免冲突。

桌面应用（Beta）

可在 releases 页面 或 opencode.ai/download 下载 macOS（Apple Silicon / Intel）、Windows、Linux（.deb / .rpm / .AppImage）安装包；macOS 也可 brew install --cask opencode-desktop。

验证安装

opencode --version
opencode --help

2.3 接入模型（/connect）

OpenCode 本身不内置模型，你需要至少接入一个提供商。最快的方式是在 TUI 内使用 /connect。

先在任意目录启动：

opencode

进入界面后输入：

/connect

然后选择提供商并粘贴 API Key。常见选择：

• OpenCode Zen（推荐新手）：官方精选并调优过的模型网关，开箱即用、按量计费。选择 opencode，前往 opencode.ai/auth 登录获取密钥。
• Anthropic / OpenAI / Google 等：选择对应提供商，粘贴你自己的 API Key。
• 本地模型（Ollama / LM Studio 等）：无需密钥，详见第五章。

也可以通过环境变量提供密钥（例如 ANTHROPIC_API_KEY、OPENAI_API_KEY），OpenCode 启动时会自动识别。

接入后，用 /models 查看并选择当前要用的模型：

/models

2.4 初始化项目（/init）

进入你要开发的项目目录后启动 OpenCode：

cd /path/to/project
opencode

运行内置命令生成项目规则文件：

/init

/init 会扫描仓库关键文件，必要时问你几个问题，然后创建或更新 AGENTS.md，把项目的构建/测试命令、目录结构、约定与「坑」沉淀下来。

建议把 AGENTS.md 提交进 Git，让团队共享同一份项目规则（详见第七章）。

2.5 第一个会话：Plan → Build 工作流

OpenCode 推荐「先规划、再实现」的工作流，这也是省 Token、降返工的好习惯。

第一步：切到 Plan（规划）模式

按 Tab 在 build / plan 之间切换。Plan 模式是只读的，默认禁止改文件、对 bash 命令要求确认，适合先让模型理解需求、给出方案：

当用户删除一条笔记时，我们希望在数据库中将其标记为已删除；
然后做一个页面展示最近删除的笔记，用户可在该页面恢复或永久删除。

像对待团队里的初级开发者一样，给足够的上下文和示例。可以用 @ 模糊搜索并引用文件，例如：

认证逻辑是如何处理的？参考 @packages/functions/src/api/index.ts

第二步：迭代方案

对返回的方案给反馈、补细节。可以直接把图片拖入终端作为参考：

这个页面参考这张设计图：[Image #1]

第三步：切回 Build（实现）模式

再次按 Tab 回到 build 模式，让它真正动手：

方案没问题，按这个去实现吧。

第四步：随时撤销 / 重做

如果结果不满意，用 /undo 回滚（包括文件改动），用 /redo 重做。可多次 /undo 连续回退。

/undo、/redo 依赖 Git 快照，请确保项目是 Git 仓库。

2.6 非交互模式（opencode run）

除了 TUI，OpenCode 也支持脚本化、一次性调用，适合自动化与 CI：

# 直接给一个问题
opencode run "用 Go 解释 context 的用法"

# 继续上一次会话
opencode run -c "继续上面的话题"

# 指定模型 / Agent
opencode run -m anthropic/claude-sonnet-4-5 --agent plan "审查这次改动"

为避免每次都冷启动（尤其是有 MCP 时），可以先起一个常驻服务再附着上去：

# 终端 A：常驻无头服务
opencode serve

# 终端 B：附着到该服务执行
opencode run --attach http://localhost:4096 "解释 JavaScript 的 async/await"

2.7 小结与下一步

到这里你已经能够：安装 OpenCode、接入模型、初始化项目、用 Plan→Build 工作流完成一次开发，并掌握撤销/重做与非交互调用。

接下来第三章会系统介绍 TUI 界面、会话管理与全部内置命令；而真正决定「用得多省、多高效」的是第四章开始的配置体系——这正是本教程的重点。