OpenCode 安装指南：多平台安装方式、桌面应用与 build/plan 双代理机制解析

OpenCode 是一个开源的 AI 编程代理（coding agent），本文基于仓库根目录的乌克兰语版 README（README.uk.md，与英文主文档 README.md 内容一一对应）系统讲解其全部安装途径——curl 脚本、npm、Homebrew、Scoop、Chocolatey、pacman、mise、Nix 等——并深入剖析仓库中随附的安装脚本 install 的底层逻辑（架构探测、baseline 回退、安装目录优先级），最后结合源码说明 build / plan / general 三个内建代理的权限差异与切换机制。读完本文，你可以完成 OpenCode 在任意主流平台上的安装与 PATH 配置，并理解其代理权限模型在源码中的实现方式。

一、项目定位

仓库自述为 “The open source AI coding agent”（开源 AI 编程代理）。OpenCode 以终端 TUI（Terminal User Interface）为主要交互形态，安装后即可在任意项目目录中通过 opencode 命令启动。安装脚本结束时会给出两步上手提示（见 install 脚本末尾输出）：

cd <project>  # 进入你的项目目录
opencode      # 运行命令启动

需要注意的是，官方提示在安装新版本前应先删除 0.1.x 以下的旧版本，避免二进制冲突。

二、安装方式总览

README 提供了两大类安装途径：一键脚本与包管理器。完整命令如下（继承自 README.md 的 Installation 章节）：

# YOLO
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（推荐，始终最新）
brew install opencode              # macOS 和 Linux（官方 Homebrew 公式，更新频率较低）
sudo pacman -S opencode            # Arch Linux（Stable）
paru -S opencode-bin               # Arch Linux（AUR 最新版）
mise use -g opencode               # 任意操作系统
nix run nixpkgs#opencode           # 或 github:anomalyco/opencode 获取最新 dev 分支

各途径的适用场景可以概括为：

途径	平台	特点
curl | bash 脚本	macOS / Linux / Windows	无需 root，安装到用户目录，自动探测架构
npm / bun / pnpm / yarn	全平台	适合已有 Node 工具链的环境，包名为 opencode-ai
Homebrew tap（anomalyco/tap）	macOS / Linux	官方推荐，更新最及时
Homebrew 官方公式	macOS / Linux	公式库收录，更新节奏较慢
Scoop / Chocolatey	Windows	两种 Windows 主流包管理器均有官方包
pacman / AUR	Arch Linux	opencode（稳定版）与 opencode-bin（AUR 最新版）
mise	任意操作系统	通过版本管理器全局安装
Nix	任意支持 Nix 的系统	nixpkgs#opencode 或指定 GitHub 仓库取 dev 分支

三、安装脚本深入解析

仓库根目录的 install 脚本正是 curl -fsSL https://opencode.ai/install | bash 下载并执行的实体，通读其源码可以弄清脚本的完整行为边界，而不只是照抄命令。

3.1 支持的命令行选项

脚本参数解析部分（install 第 10–27 行的 usage 说明）定义了三个选项：

-v, --version <version>   安装指定版本（如 1.0.180）
-b, --binary <path>       跳过下载，从本地二进制文件安装
    --no-modify-path      不修改 shell 配置文件（.zshrc、.bashrc 等）

对应的实际用法：

# 固定安装某个版本
curl -fsSL https://opencode.ai/install | bash -s -- --version 1.0.180

# 从本地构建产物安装
./install --binary /path/to/opencode

其中 --version 会先通过 GitHub API 校验该 tag 是否存在，404 时直接报错退出；--binary 则会跳过全部下载与架构探测逻辑，直接把本地文件复制并 chmod 755 到安装目录。

3.2 平台与架构探测逻辑

脚本只接受五种目标组合：linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64，其余组合直接报错退出。在基础探测之上还有三个值得注意的细节：

1. Rosetta 识别（Darwin x64）：通过 sysctl.proc_translated 判断当前是否运行在 Rosetta 翻译环境下，若是则把架构改写为 arm64，从而为 Apple Silicon 下载原生二进制而不是 x64 版本。
2. musl 检测（Linux）：通过 /etc/alpine-release 或 ldd --version 输出识别 musl libc（如 Alpine），在目标名后追加 -musl 后缀，保证静态链接兼容。
3. AVX2 能力探测（baseline 回退）：x64 平台上会检测 CPU 是否支持 AVX2——Linux 读 /proc/cpuinfo，macOS 读 sysctl hw.optional.avx2_0，Windows 则调用 kernel32!IsProcessorFeaturePresent(40)（通过 powershell/pwsh 执行）。不支持 AVX2 的机器会在目标名后追加 -baseline，下载不带 AVX2 指令的构建产物。这说明官方预编译产物按 CPU 特性分档发布，老服务器不会因指令集不兼容而崩溃。

产物格式方面，Linux 使用 .tar.gz（要求系统有 tar），其他平台使用 .zip（要求 unzip），缺少对应工具时脚本会提前报错退出。

3.3 版本幂等性检查

check_version 函数会先 which opencode，若已安装则执行 opencode --version 比对目标版本：版本一致时直接打印 “already installed” 并退出，版本不一致时才继续下载安装。这意味着重复执行安装脚本是安全且幂等的。

3.4 PATH 配置策略

默认安装目录为 $HOME/.opencode/bin（即 README 中所述的“Default fallback”）。安装后脚本按当前 shell（fish / zsh / bash / ash / sh）选择对应的 rc 文件，将安装目录写入 PATH：

• zsh 依次检查 ~/.zshrc、~/.zshenv 及 XDG 路径下的同名文件；
• bash 依次检查 ~/.bashrc、~/.bash_profile、~/.profile 及 XDG 路径；
• fish 使用 fish_add_path 语句，其余 shell 写入 export PATH=...；
• 写入前会先 grep 判重，已存在则跳过；文件不可写时打印手动添加的提示而不是硬写；
• 若检测到 GITHUB_ACTIONS=true，还会把安装目录追加进 $GITHUB_PATH，方便在 CI 中直接调用。

配合 --no-modify-path 选项，可以在完全不动 shell 配置的前提下完成安装，适合容器或受限环境。

四、安装目录优先级

README 中“Installation Directory / Каталог встановлення”一节给出了安装脚本对安装路径的四级优先级，结合 install 脚本源码可完整还原其语义：

1. $OPENCODE_INSTALL_DIR — 自定义安装目录（最高优先级）；
2. $XDG_BIN_DIR — 兼容 XDG Base Directory 规范的路径；
3. $HOME/bin — 标准用户二进制目录（若已存在或可创建）；
4. $HOME/.opencode/bin — 默认回退路径（脚本中 INSTALL_DIR 的初始值）。

README 给出的两个自定义示例：

# 安装到系统目录（通常需要相应权限）
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# 指定 XDG 二进制目录
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

五、桌面应用（BETA）

OpenCode 同时提供桌面客户端，目前处于 BETA 阶段，可从官方发布页直接下载各平台安装包：

平台	下载产物
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、主进程 src/main/ 与预加载脚本 src/preload/ 等），桌面端的图标资源按 beta、dev、prod 三套发布渠道分别维护，与 BETA 阶段的发布策略相吻合。

六、内建代理：build / plan / general

README 的 “Agents” 章节说明 OpenCode 提供两个可用 Tab 键切换的内建主代理，另有一个辅助子代理：

• build — 默认代理，拥有完整权限，面向开发任务；
• plan — 只读分析代理：默认拒绝文件编辑、执行 bash 命令前请求授权，适合探索不熟悉的代码库或规划改动；
• general — 用于复杂搜索与多步骤任务的子代理，系统内部使用，也可在消息中通过 @general 显式调用。

6.1 源码中的代理定义

三个代理的具体实现集中在 agent.ts。从源码结构看，每个代理由 mode（primary / subagent / all）、permission（权限规则集）和可选的 prompt、model、temperature 等字段构成，权限通过 Permission.merge 按 “默认规则 → 代理专属规则 → 用户配置” 的顺序逐层合并：

• build（agent.ts）：mode: "primary"，在默认权限基础上放开 question 与 plan_enter，即默认权限集（读取 .env* 文件会询问、doom_loop 询问等）之上获得完整的执行能力。
• plan（agent.ts）：核心约束是 edit: { "*": "deny" }——全局拒绝编辑，仅放行 .opencode/plans/*.md 与全局数据目录下的 plans/*.md，这解释了“只读”并非完全无法写盘，而是只允许把规划落盘为 Markdown 计划文件；同时 task: { general: "deny" } 表明 plan 模式下不会派生 general 子任务。
• general（agent.ts）：mode: "subagent"，描述为“用于研究复杂问题、执行多步骤任务，可并行执行多个工作单元”，仅额外禁用了 todowrite 工具，其余继承默认权限。

此外源码中还定义了若干 README 未展开的代理，可以补充理解 OpenCode 的代理体系：

• explore（agent.ts）：专门的代码库探索子代理，权限为“默认拒绝 + 白名单”，仅允许 grep、glob、list、bash、webfetch、websearch、read 等只读类工具，且外部目录访问保持只读。
• compaction / title / summary：hidden: true 的系统代理，分别用于上下文压缩、会话标题生成与会话摘要，全部工具默认拒绝，说明这些是纯 LLM 推理任务而非工具型代理。

6.2 用户自定义代理的合并机制

agent.ts 展示了配置覆盖逻辑：用户可通过配置中的 agent 段按名称扩展或覆盖任意代理（包括内建代理），支持 model、prompt、description、temperature、top_p、mode、color、hidden、steps、options、permission 等字段；设置 disable: true 可以直接移除某个内建代理。用户的权限规则永远在合并链的最后一层生效，因此可以对内建代理做精细化收权。

6.3 TUI 中的代理切换

README 提到的 Tab 键切换，对应 TUI 中的 agent.cycle / agent.cycle.reverse 命令（app.tsx），二者通过 local.agent.move(±1) 在代理列表中前进/后退一位；主屏幕提示视图也内置了 “press … to cycle between Build and Plan agents” 的引导文案（tips-view.tsx）。代理列表的排序规则则遵循“默认代理（或 build）优先、其余按名称升序”（见 agent.ts），保证 Tab 循环时默认代理始终排在前位。

七、延伸阅读与贡献

• 完整的配置说明（模型、权限、代理、主题等）以官方文档站为准，README 在 Documentation 一节将其作为配置问题的唯一权威入口。
• 参与贡献前请先阅读 CONTRIBUTING.md，其中约定了 pull request 前的阅读要求。
• 命名约定：如果你的项目名中包含 “opencode”（如 “opencode-dashboard”、“opencode-mobile”），README 要求在其 README 中明确声明该项目并非 OpenCode 团队开发、与官方无任何隶属关系，避免社区混淆。
• 多语言 README：仓库根目录维护了包括英文（README.md）、简体中文（README.zh.md）、乌克兰文（README.uk.md）在内的二十余个语言版本，内容骨架一致。

八、小结

要点	说明
推荐安装	Linux/macOS 首选 brew install anomalyco/tap/opencode；Windows 用 Scoop/Chocolatey；无包管理器环境用 curl 脚本
固定版本	curl … | bash -s -- --version <ver>，脚本会校验 tag 存在性
安装位置	默认 ~/.opencode/bin，可用 OPENCODE_INSTALL_DIR / XDG_BIN_DIR 覆盖
产物分档	按 OS-架构 组合发布，另有 -baseline（无 AVX2）与 -musl（Alpine）变体
代理模型	build（全权限）/ plan（只读，仅可写 plans Markdown）/ general（子代理，@general 调用），Tab 循环切换
扩展性	通过配置 agent 段覆盖任意内建代理的模型、提示词与权限

以上内容均可在仓库中逐一核验：安装行为见 install，代理定义与权限合并见 packages/opencode/src/agent/agent.ts，TUI 切换命令见 packages/tui/src/app.tsx，文档骨架见 README.md 与 README.uk.md。