OpenCode 安装与内置代理机制详解：多平台安装方式、安装目录优先级与 build/plan/general 代理权限设计

OpenCode 是一个开源的终端 AI 编程代理（coding agent）。本文以仓库根目录的官方 README 为骨架，完整覆盖其全部安装渠道、桌面应用（BETA）获取方式与安装目录优先级规则，并结合仓库内 install 脚本 与 agent.ts 等源码，深入讲解 build / plan / general 三类内置代理的权限模型与切换机制，帮助你在安装 OpenCode 后快速建立可用的开发工作流。

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

OpenCode 的官方定位是 "The open source coding agent"，即一个以终端为交互界面、可自主执行编码任务的 AI 代理。它以 npm 包 opencode-ai 的形式发布，同时提供独立的二进制安装脚本和桌面客户端。从仓库结构看，核心执行逻辑位于 packages/opencode，TUI 界面位于 packages/tui，桌面端位于 packages/desktop，服务端与 API 层分别位于 packages/server 与 packages/sdk。

二、安装方式全览

OpenCode 支持多种安装渠道，覆盖 macOS、Linux 与 Windows，可按操作系统与包管理习惯任选其一：

# 安装脚本（一键安装）
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 formula，更新较少）
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 分支

渠道选择要点：

• 一键脚本：适合没有首选包管理器的环境，直接下载对应平台的预编译二进制；
• npm / bun / pnpm / yarn：以 opencode-ai@latest 包名全局安装，适合已有 Node 工具链的开发者；
• Homebrew：anomalyco/tap/opencode 走官方 tap 源，更新频率高于社区维护的 brew install opencode formula；
• Nix：nix run nixpkgs#opencode 使用稳定版，github:anomalyco/opencode 可追平开发分支。

提示：升级前建议先卸载 0.1.x 及更早的旧版本，避免新旧版本共存导致命令冲突或配置不兼容。

三、桌面应用（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 Cask）
brew install --cask opencode-desktop
# Windows（Scoop）
scoop bucket add extras; scoop install extras/opencode-desktop

桌面端源码位于 packages/desktop，基于 Tauri 构建（见 packages/containers/tauri-linux/Dockerfile 与构建配置 electron-builder.config.ts 相关工程），图标资源按 dev/prod 与 beta 渠道分离存放于 packages/desktop/icons。

四、安装目录：优先级顺序与环境变量

安装脚本在下载二进制后会选择一个安装位置。按优先级从高到低依次为：

1. $OPENCODE_INSTALL_DIR —— 自定义安装目录；
2. $XDG_BIN_DIR —— 遵循 XDG Base Directory 规范的 bin 路径；
3. $HOME/bin —— 标准用户 bin 目录（目录已存在或可创建时）；
4. $HOME/.opencode/bin —— 默认兜底位置。

可以通过环境变量显式指定安装位置：

# 示例一：安装到系统路径
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

4.1 仓库 install 脚本的默认行为

仓库根目录的 install 脚本是上述一键安装的参考实现，当前版本的默认安装目录为兜底位置 $HOME/.opencode/bin（见 install 第 68 行）。脚本还支持若干命令行选项（见 usage 函数，install 第 10–27 行）：

选项	说明
-v, --version <ver>	安装指定版本，例如 --version 1.0.180
-b, --binary <path>	跳过下载逻辑，直接安装本地二进制文件
--no-modify-path	不修改 shell 配置文件（.zshrc、.bashrc 等）
-h, --help	显示帮助信息

用法示例：

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

4.2 平台检测与二进制选择

从源码结构看，install 脚本在安装前会完成一系列环境探测（install 第 79–168 行）：

• 系统识别：uname -s 映射为 darwin / linux / windows（含 MINGW、MSYS、CYGWIN）；
• 架构归一：aarch64 → arm64、x86_64 → x64；在 Intel Mac 上通过 Rosetta 运行（sysctl.proc_translated 为 1）时自动改选 arm64 包；
• Linux 打包格式：Linux 使用 .tar.gz，其余平台使用 .zip；
• musl 检测：Alpine（存在 /etc/alpine-release）或 ldd --version 输出包含 musl 的系统，会追加 -musl 后缀；
• baseline 检测：x64 平台若 CPU 不支持 AVX2（Linux 查 /proc/cpuinfo，macOS 查 hw.optional.avx2_0，Windows 通过 PowerShell 查询处理器特性位 40），会追加 -baseline 后缀，选择兼容指令集的构建变体。

最终下载的文件名形如 opencode-linux-x64.tar.gz 或 opencode-darwin-arm64.zip，来源为官方 releases 的最新或指定版本。

4.3 PATH 自动配置

安装完成后，脚本会根据 $SHELL 判断当前 shell 类型（fish / zsh / bash / ash / sh），并将 $INSTALL_DIR 写入对应的配置文件（install 第 380–439 行）：

• fish：fish_add_path；
• zsh / bash / ash / sh：export PATH=... 追加写入 .zshrc、.zshenv、.bashrc、.profile 等候选文件（含 XDG 路径下的同名文件）；
• 重复安装时通过 grep -Fxq 幂等检测，避免重复写入；
• 在 GitHub Actions 环境中还会追加到 $GITHUB_PATH，便于 CI 中直接使用；
• 传入 --no-modify-path 可跳过全部 PATH 修改逻辑。

五、内置代理：build、plan 与 general

OpenCode 内置两个可切换的主代理（primary agent），在 TUI 中按 Tab 键切换：

• build —— 默认代理，具备完整的开发权限（执行编辑、运行命令等）；
• plan —— 只读分析代理，用于代码调研与方案规划：
  • 默认禁止修改文件；
  • 运行 bash 命令前需要用户授权；
  • 适合调研陌生代码库或规划复杂改动。

此外还内置 general 子代理（subagent），面向复杂检索与多步骤任务，它由系统内部调用，用户也可以在消息中通过 @general 显式调用。

5.1 源码中的代理定义与权限模型

三个代理在 packages/opencode/src/agent/agent.ts 第 140–195 行 中被静态定义，并通过权限合并（Permission.merge）机制叠加默认权限、代理专属权限与用户配置权限：

• build（mode: "primary"）：在默认权限上放开 question（允许向用户提问）与 plan_enter（允许进入计划模式）；
• plan（mode: "primary"）：
  • edit 全局 deny，但放行 .opencode/plans/*.md 与全局数据目录下的 plans 路径——即计划代理只能写"计划文档"，不能动业务代码；
  • task: { general: "deny" }，禁止计划阶段派生 general 子代理并行执行；
  • plan_exit: "allow"，允许调用退出计划工具；
• general（mode: "subagent"）：通用多步骤执行代理，仅额外禁用 todowrite（避免子代理维护主会话 TODO 状态）。

README 中"plan 代理运行 bash 前需要授权"这一点，对应到 agent.ts 第 120–128 行 的默认权限集：doom_loop（防止循环操作）与 external_directory（工作区外目录）均为 ask，读取 *.env 等敏感文件也是 ask，仅 *.env.example 放行——这就是 plan 阶段"只读、受控"的具体实现。

5.2 从 plan 切回 build：plan_exit 工具

计划完成后的切换由 packages/opencode/src/tool/plan.ts 中的 plan_exit 工具驱动（第 15–79 行），流程是：

1. 向用户弹出确认问题："Plan at {plan} is complete. Would you like to switch to the build agent and start implementing?"，选项为 Yes（切换到 build 并开始实现）/ No（留在 plan 继续完善计划）；
2. 用户选择 No 时抛出 Question.RejectedError，会话保持在 plan 模式；
3. 用户选择 Yes 时，工具向会话注入一条 agent: "build" 的合成用户消息，附带 "The plan at {plan} has been approved, you can now edit files. Execute the plan" 指令，随后权限从"只读"切换为 build 的完整权限。

这一设计让"先规划、后执行"成为显式的、用户可控的两阶段流程，而不是隐式的模式漂移。

5.3 general 子代理的定位

general 的描述明确写着：用于研究复杂问题并执行多步骤任务，适合并行执行多个工作单元。它属于 subagent 模式，即不直接与用户对话，而是被主代理（或用户通过 @general）派生调用；plan 代理则被显式禁止派生它，以保证规划阶段保持只读。

六、文档、贡献与命名规范

• 配置文档：OpenCode 的完整配置说明位于官方文档站（opencode.ai/docs），仓库内 packages/docs 收录了快速开始、设置、可复用片段等 mdx 文档源。
• 贡献指南：向 OpenCode 提交 PR 前，请先阅读 CONTRIBUTING.md。
• 命名免责声明：如果你的项目与 OpenCode 相关、并在名称中使用 "opencode"（例如 "opencode-dashboard"、"opencode-mobile"），README 要求你在项目说明中注明"该项目并非由 OpenCode 团队开发，与其无关联"，以避免品牌混淆。

七、小结

围绕 README 的核心信息，可以把 OpenCode 的使用路径归纳为三步：

1. 安装：按平台选择 curl 脚本、npm、Homebrew、Scoop/Chocolatey、pacman/AUR、mise 或 Nix，注意卸载 0.1.x 旧版本，必要时用 OPENCODE_INSTALL_DIR / XDG_BIN_DIR 控制安装位置；
2. 理解权限：build 代理拥有完整开发权限，plan 代理只能写计划文档并需授权运行命令，切换由 plan_exit 工具显式触发；
3. 善用子代理：复杂检索与多步骤任务交给 general，用户可用 @general 显式调用。

以上安装参数、目录优先级与代理权限行为均以当前仓库的 install 脚本、agent.ts 与 plan.ts 的实际实现为准；若后续版本调整了默认安装目录或权限合并逻辑，请以仓库最新代码为准。