OpenCode 开源编码代理：多平台安装方式、安装目录优先级与内置 Agent 机制详解

本文基于 OpenCode 仓库根目录的土耳其语版 README（README.tr.md）展开，完整覆盖其安装渠道、桌面应用（BETA）分发形式、安装目录优先级规则以及内置 build/plan/general 三类 Agent 的行为定义，并结合仓库中的 install 脚本 与 Agent 源码 进一步解析其底层实现。读完后你可以掌握 OpenCode 在各种操作系统上的正确安装方式，理解其权限驱动的 Agent 体系，并能通过配置文件自定义 Agent 与默认行为。

项目定位

OpenCode 定位为"开源 AI 编码代理"（The open source AI coding agent），即运行于终端的智能编码助手，内置免费模型，安装完成后在项目目录中执行 opencode 即可开始使用。仓库同时维护了 20 余种语言的 README（README.md、README.zh.md、README.tr.md 等），各版本内容与英文原版保持一致。

安装方式

README 中给出的完整安装矩阵如下（原文为土耳其语，此处保留原始命令）：

# 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（官方 brew formula，更新较少）
sudo pacman -S opencode            # Arch Linux（Stable）
paru -S opencode-bin               # Arch Linux（AUR 最新版）
mise use -g opencode               # 任意操作系统
nix run nixpkgs#opencode           # 或 nix 开发分支

需要注意的升级提示：安装前应先移除 0.1.x 之前的旧版本，避免新旧二进制冲突。

install 脚本的源码级细节

上述 curl | bash 方式实际执行的就是仓库根目录的 install 脚本。从源码结构看，该脚本提供了 README 未展开的三个可选参数：

-h, --help              显示帮助
-v, --version <version> 安装指定版本（例如 1.0.180）
-b, --binary <path>     从本地二进制文件安装，跳过下载与平台检测
    --no-modify-path     不修改 shell 配置文件（.zshrc、.bashrc 等）

对应用法示例（摘自脚本内 usage()，见 install）：

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

脚本内部的几个关键实现点值得了解：

1. 平台与架构检测：通过 uname -s/uname -m 归一化为 darwin|linux|windows 与 x64|arm64，仅支持 linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64 五种组合（install）；macOS 上会检查 Rosetta 转译标记，若 x64 进程实际跑在 Apple Silicon 上则改用 arm64 产物（install）。
2. CPU 特性与 libc 适配：x64 目标下会检测 AVX2 指令集（Linux 读 /proc/cpuinfo、macOS 读 sysctl hw.optional.avx2_0、Windows 调 IsProcessorFeaturePresent），不具备时追加 -baseline 产物后缀；Linux 还会通过 /etc/alpine-release 与 ldd --version 判断是否为 musl 环境并追加 -musl 后缀（install）。这解释了为什么 Release 资产中存在大量变体文件。
3. 幂等的 PATH 注入：安装后脚本按当前 shell（fish/zsh/bash/ash/sh）选择合适的配置文件，将安装目录写入 $PATH，并带 grep -Fxq 去重，避免重复追加；在 GitHub Actions 环境中则写入 $GITHUB_PATH（install）。这也是 --no-modify-path 选项存在的意义——CI 或受管环境可显式接管 PATH。
4. 下载进度渲染：终端环境使用 curl --trace-ascii 配合 FIFO 管道实时绘制进度条，非 TTY（如 CI）自动回退到标准 curl -#（install）。

桌面应用（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 目录（Tauri 技术栈），其构建脚本与图标资源见 packages/desktop/scripts 与 packages/desktop/icons。

安装目录优先级

README 定义了安装脚本在选择安装路径时的优先级顺序：

1. $OPENCODE_INSTALL_DIR — 自定义安装目录
2. $XDG_BIN_DIR — 符合 XDG Base Directory Specification 的路径
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

需要说明实现现状：仓库当前版本的 install 脚本将安装目录硬编码为 INSTALL_DIR=$HOME/.opencode/bin，并未读取 $OPENCODE_INSTALL_DIR/$XDG_BIN_DIR 等变量。从文档与源码的差异可以推断，上述四级优先级是安装器对外承诺/演进中的目标行为，而当前仓库快照中的脚本实现的是第 4 级默认值；如果你依赖自定义目录，建议以实际执行的脚本内容为准并自行校验安装位置。

内置 Agent：build、plan 与 general

OpenCode 内置两个可用 Tab 键切换的主 Agent，外加一个内部子 Agent：

• build — 默认 Agent，面向开发工作的全权限代理；
• plan — 面向分析与代码探索的只读 Agent：默认拒绝文件编辑、执行 Bash 命令前请求许可，适合探索陌生代码库或规划变更；
• general — 面向复杂搜索与多步任务的通用子 Agent，内部使用，可在消息中通过 @general 显式调用。

源码中的 Agent 注册与权限模型

三个内置 Agent 的完整定义位于 agent.ts（packages/opencode/src/agent/agent.ts）。每个 Agent 是一个 Info 结构，核心字段包括 name、description、mode（subagent/primary/all 三选一）、hidden、model、prompt、temperature/topP、steps 以及最重要的 permission 规则集（见 Info 模式定义）。

build（定义处）：mode: "primary"、native: true，权限在默认规则基础上放开了 question 与 plan_enter，即允许向用户提问并允许进入 plan 模式。

plan（定义处）：权限合并中显式设置了 edit: { "*": "deny" }，这就是"默认拒绝文件编辑"的实现；同时保留了两个例外，允许写入 .opencode/plans/*.md 与全局数据目录下的 plans/*.md，使 Agent 在只读模式下仍能把计划落成 Markdown 文档。此外它放开了 plan_exit（允许退出 plan 模式）、拒绝了 task.general（plan 模式下不允许再派生 general 子任务）。TUI 侧对 plan_enter/plan_exit 工具事件有专门的状态处理，见 session 路由。

general（定义处）：mode: "subagent"，权限相对默认值仅收紧了 todowrite，用于研究复杂问题与并行执行多步工作。

除 README 提及的三个 Agent 外，源码中还注册了 explore（面向代码库快速检索的子 Agent）以及 compaction、title、summary 三个 hidden: true 的内部 Agent，它们服务于上下文压缩、会话标题与摘要生成，不会出现在用户可切换列表中。Agent 列表的可见性过滤逻辑（mode === "subagent" 或 hidden 者不可选）在 v2 Agent 服务 中同样有对应实现。

权限的三层合并

从源码结构看，所有 Agent 的权限按"默认规则 → Agent 内置覆盖 → 用户配置"的顺序通过 Permission.merge 逐层合并：

1. 默认规则（agent.ts）："*": "allow"，但 doom_loop、question、plan_enter、plan_exit 收紧为 ask/deny；外部目录默认 ask（技能目录、参考目录等白名单除外）；读取 *.env、*.env.* 文件时要求询问（*.env.example 放行）。
2. Agent 内置覆盖：如上文 build/plan/general 各自的 Permission.fromConfig({...})。
3. 用户配置：cfg.permission 来自 OpenCode 配置文件，最终合并进每个 Agent（agent.ts），因此你可以全局收紧或放宽任意权限。

用配置自定义 Agent 与默认 Agent

源码在注册内置 Agent 后还会遍历 cfg.agent（agent.ts），支持：

• 用 disable: true 删除同名内置 Agent；
• 新增自定义 Agent（默认 mode: "all"），并可覆盖 model、variant、prompt、description、temperature、top_p、mode、color、hidden、steps、options 与 permission，其中 options 与 permission 采用深度合并而非整体替换。

默认 Agent 的解析逻辑见 defaultInfo：若配置了 default_agent，则校验其存在、非 subagent、非 hidden 后返回；否则回退到第一个可见的 primary Agent。Agent 排序也会将 default_agent 指定的 Agent 置顶（list）。

贡献与命名规范

• 提交 Pull Request 前请先阅读 CONTRIBUTING.md。
• README 还特别约定：如果你的项目名称中包含 "opencode"（如 "opencode-dashboard"、"opencode-mobile"），请在其 README 中注明该项目并非 OpenCode 团队开发、与其无任何关联。

小结

OpenCode 的分发体系覆盖了 curl 安装器、npm/scoop/choco/brew/pacman/paru/mise/nix 等多种渠道，安装器内部做了平台检测、baseline/musl 产物选择与幂等的 PATH 注入；其 Agent 体系则以"权限规则集合并"为核心机制，用同一套 permission 模型同时支撑了 build 的全权限开发、plan 的只读分析与 general 的子任务执行。若需进一步了解各配置项（permission、agent、default_agent 等）的完整语义，可查阅仓库内 packages/opencode 的 AGENTS.md 与 specs/v2 下的规格文档。