OpenCode 安装与使用指南：从安装脚本到 build/plan 代理系统的源码级解析

2026-09-04 10:56:15作者：温玫谨Lighthearted

本文基于 OpenCode 仓库的官方 README（含 README.gr.md 等多语言版本）整理，覆盖 OpenCode 的全部安装渠道、安装脚本的内部工作机制、Desktop 桌面应用获取方式，以及内置 build / plan / general 代理的权限设计。读完后你将能够：在任意主流操作系统上正确安装并配置 OpenCode 的 PATH，看懂官方安装脚本的版本检测与 CPU 特性判断逻辑，并理解 OpenCode 内置代理的权限边界及其在源码中的实现位置。

一、项目定位：开源编码代理

OpenCode 官方对自身的定位是「开源的编码 AI 代理」（The open source coding agent）。它以终端 TUI 为核心交互形态，同时提供 TUI、CLI、Desktop 多种运行方式，npm 包名为 opencode-ai。仓库根目录的 install 脚本、packages/opencode 核心实现、packages/tui 终端界面以及 packages/desktop 桌面端，共同构成了这套代理的完整交付形态。

二、安装方式全览

官方文档提供了以下安装渠道，可按操作系统与偏好任选其一：

# 一键安装脚本
curl -fsSL https://opencode.ai/install | bash

# 包管理器
npm i -g opencode-ai@latest        # 或 bun / pnpm / yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS 和 Linux（官方 tap，更新最及时）
brew install opencode              # macOS 和 Linux（brew 官方源，更新频率较低）
sudo pacman -S opencode            # Arch Linux（稳定仓库）
paru -S opencode-bin               # Arch Linux（AUR 最新构建）
mise use -g opencode               # 跨平台
nix run nixpkgs#opencode           # 或基于 dev 分支最新提交的源码构建

提示：如果系统中存在 0.1.x 之前的旧版本，建议先卸载再安装新版，以避免行为差异。

仓库中 Nix 构建的具体定义可参考 nix/opencode.nix 与 flake.nix，nix run nixpkgs#opencode 使用的就是这套 Nix 表达式。

三、安装脚本深度解析：仓库根目录 `install` 脚本

一键脚本的真实实现就是仓库根目录的 install（约 460 行 Bash 脚本）。读懂它，能解释「为什么安装后 opencode 命令直接可用」这类常见问题。

3.1 支持的命令行选项

脚本开头通过 usage() 函数定义了三个可选项：

选项	作用
`-v, --version <version>`	安装指定版本（例如 `1.0.180`），不带 `v` 前缀也可，脚本会自动剥离前缀并先通过 HTTP HEAD 请求校验该 release 是否存在（404 则报错退出）
`-b, --binary <path>`	跳过所有下载与平台检测逻辑，直接拷贝本地二进制文件
`--no-modify-path`	不修改 shell 配置文件（`.zshrc`、`.bashrc` 等）

用法示例（来自脚本内嵌文档）：

curl -fsSL https://opencode.ai/install | bash
curl -fsSL https://opencode.ai/install | bash -s -- --version 1.0.180
./install --binary /path/to/opencode

3.2 平台检测：OS、架构与两种特殊构建

脚本的下载目标不是单一文件，而是按平台组合（os-arch）动态计算出的 release 资产名，其中包含两个容易忽略的分支：

musl 构建：Linux 下若检测到 /etc/alpine-release 或 ldd --version 输出含 musl，会在目标后缀追加 -musl（install#L117-L128）。这解释了为什么 Alpine 等 musl 发行版不能直接用 glibc 构建的二进制。
baseline（无 AVX2）构建：x64 平台下，脚本会检查 CPU 是否支持 AVX2——Linux 读 /proc/cpuinfo、macOS 读 hw.optional.avx2_0、Windows 通过 PowerShell 调用 IsProcessorFeaturePresent；不支持时目标追加 -baseline 后缀（install#L130-L166）。这保证旧 CPU 也能运行。

另外，macOS Intel 环境下脚本会通过 sysctl.proc_translated 检测 Rosetta 转译，若在 Rosetta 下运行则强制选择 arm64 构建。支持的组合为：linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64（Linux 用 .tar.gz，其余用 .zip）。

3.3 版本幂等与 PATH 配置

幂等检查：安装前先执行 opencode --version，若已安装版本与目标一致则直接退出（check_version 函数，install#L221-L235），重复执行脚本不会产生副作用。
PATH 配置：脚本按当前 shell 类型（fish / zsh / bash / ash / sh）探测对应的配置文件，将 export PATH=<安装目录>:$PATH 写入其中；若配置文件不可写，则打印手动添加的提示。未加 --no-modify-path 时该步骤默认执行。
CI 友好：检测到 GITHUB_ACTIONS=true 时，会把安装目录追加进 $GITHUB_PATH，供后续 workflow 步骤使用（install#L441-L444）。

3.4 安装目录优先级

README 文档中声明，安装脚本按以下优先级决定安装目录：

$OPENCODE_INSTALL_DIR — 自定义安装目录
$XDG_BIN_DIR — XDG Base Directory 规范路径
$HOME/bin — 用户可执行目录（存在或可创建时）
$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

需要注意的证据边界：在当前仓库快照的 install 脚本中，第 68 行写死的默认值正是第 4 级兜底路径 $INSTALL_DIR=$HOME/.opencode/bin，而前几级环境变量优先级未在脚本正文中出现。可以推断前 3 级逻辑由线上分发的部署脚本承载，与仓库内脚本存在版本差异；以仓库脚本为准的稳妥结论是：默认安装到 $HOME/.opencode/bin，且该路径会被自动加入 PATH。

四、Desktop 桌面应用（BETA）

除终端形态外，OpenCode 也提供桌面应用（BETA 阶段），可从官方发行版页面或 opencode.ai/download 直接下载。各平台安装包如下：

平台	下载产物
macOS（Apple Silicon）	`opencode-desktop-mac-arm64.dmg`
macOS（Intel）	`opencode-desktop-mac-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb`、`.rpm` 或 AppImage

也可通过包管理器安装：

# macOS（Homebrew）
brew install --cask opencode-desktop
# Windows（Scoop）
scoop bucket add extras; scoop install extras/opencode-desktop

桌面端的构建配置位于 packages/desktop/electron-builder.config.ts，图标按 dev / beta / prod 三套环境区分存放于 packages/desktop/icons，与上表「BETA」定位相对应。

五、代理系统：build / plan / general

README 明确说明：OpenCode 内置两个可切换的一级代理，在 TUI 中通过 Tab 键切换，另有一个 general 子代理用于复杂检索与多步任务。这段描述在源码中有直接对应——packages/opencode/src/agent/agent.ts 定义了全部内置代理：

5.1 build（默认代理，mode: primary）

描述：「The default agent. Executes tools based on configured permissions.」
权限：在默认权限（工具全允许、doom_loop 需询问、外部目录默认询问、*.env 文件读取需询问）之上，追加 question: "allow"、plan_enter: "allow"，允许自由读写与执行，是日常改代码的主力。
它也是全链路的最终回退：当配置了 default_agent 时优先使用配置值，否则回退到 build（可参见 packages/opencode/src/agent/agent.ts#L322 的默认代理排序逻辑，以及 packages/opencode/src/cli/cmd/run/runtime.lifecycle.ts#L125 中 input.agent ?? "build" 的兜底）。

5.2 plan（只读分析代理，mode: primary）

描述：「Plan mode. Disallows all edit tools.」
权限：在默认权限之上显式设置 edit: {"*": "deny"}，即默认拒绝一切文件编辑；唯一的例外是允许写入计划文件——.opencode/plans/*.md 与全局数据目录下的 plans/*.md（agent.ts#L171-L175）。
配合 plan_exit: "allow"，plan 代理可以在分析完代码后申请切回 build 模式执行改动。它适合探索陌生代码库或先设计后实施的场景。

5.3 general（子代理，mode: subagent）

描述：面向复杂问题研究与多步骤任务，可并行执行多个工作单元；在权限上禁用了 todowrite 工具。
使用方式：在会话消息中通过 @general 调用。README 中「内部使用、可通过 @general 唤起」的说明与其 mode: "subagent" 的源码定义一致。
补充一点：同一文件中还定义了只读检索型的 explore 子代理（仅允许 grep / glob / list / read / bash 等只读工具，agent.ts#L196-L218），README 未提及它，属于源码层面的补充信息。

5.4 权限合并机制

每个内置代理的权限都由三层 Permission.merge 合成：系统默认权限 → 代理专属权限 → 用户配置权限（cfg.permission，agent.ts#L119-L152）。这意味着用户可以在配置文件的 permission 字段覆盖内置行为（例如收紧 build 的 bash 权限），这也是理解 OpenCode 权限体系的入口：代理不是简单的"开关"，而是可叠加、可覆盖的权限集合。

六、后续指引

使用文档：README 将更深入的使用说明指向官方文档站（opencode.ai/docs），仓库内配套的文档源码位于 packages/web/src（Mintlify 文档站，含 600 余篇 .mdx 页面），OpenAPI 规范见 packages/docs/openapi.json。
贡献流程：参与开发前请先阅读 CONTRIBUTING.md，仓库对构建、测试与发布有完整约定；核心包的工程约束另见 packages/opencode/AGENTS.md。
命名规范：官方要求，若你的项目名包含 "opencode"（如 "opencode-dashboard"），需在 README 中声明该项目并非 OpenCode 官方团队构建、与官方无关。

七、小结

主题	关键结论	证据位置
安装	curl 脚本 + npm/scoop/choco/brew/pacman/mise/nix 多渠道	README.gr.md、install
安装脚本	支持指定版本/本地二进制；musl 与 baseline(AVX2) 自动降级；幂等检查与 PATH 自动配置	install#L112-L166、install#L221-L235
安装目录	文档声明 4 级优先级；仓库脚本默认 `$HOME/.opencode/bin`	install#L68
Desktop	BETA 阶段，四大平台安装包，Homebrew/Scoop 可装	packages/desktop
代理	build（默认全权限）、plan（默认禁编辑，仅可写 plans）、general（@general 调用的子代理）	packages/opencode/src/agent/agent.ts#L140-L195