OpenCode 安装、分发与内置 Agent 机制全解：从安装脚本到 build/plan/general 的源码级剖析

2026-09-06 13:49:41作者：曹令琨Iris

OpenCode 是一个开源 AI 编码代理（coding agent），本文围绕项目根目录 README 所介绍的核心内容展开：多平台安装方式与安装脚本的目录优先级、Beta 版桌面应用的各平台安装包、以及内置的 build / plan / general Agent 体系。读完本文，你将不仅能照做完成 OpenCode 的本地安装与 PATH 配置，还能理解安装脚本如何探测 CPU 特性选择正确的二进制、各内置 Agent 的权限边界在源码中是如何定义的，从而在生产与 CI 环境中稳定使用它。

一、安装：一条命令与十种包管理器

OpenCode 的安装分为两大类：官方安装脚本（README 中戏称为 "YOLO" 模式）和通过主流包管理器安装。完整命令集合如下（与 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           # 或使用 github:anomalyco/opencode 跟踪最新 dev 分支

README 同时给出一条重要提示：安装前请先删除 0.1.x 之前的旧版本（早期版本与新版本在配置目录和 CLI 行为上不兼容）。

安装脚本支持哪些命令行参数

仓库根目录的 install 脚本就是上述 curl ... | bash 拉取并执行的脚本。从源码看，它支持以下参数（见 install 中的 usage 说明）：

参数	说明
`-h, --help`	显示帮助信息
`-v, --version <version>`	安装指定版本，例如 `1.0.180`（脚本会自动剥离前导 `v`）
`-b, --binary <path>`	跳过下载与平台探测逻辑，直接安装本地二进制
`--no-modify-path`	不修改 shell 配置文件（`.zshrc`、`.bashrc` 等）

典型用法：

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

# 从本地构建产物安装（适合 CI 或离线环境）
./install --binary /path/to/opencode

指定版本时，脚本会先通过 HTTP HEAD 请求校验该 release 是否存在，404 时直接报错并提示可用的 release 列表（install）。

平台探测、musl 与 baseline 变体

安装脚本并非"下载一个文件"这么简单，它的下载 URL 是一个由 os-arch 组合而成的平台产物名，支持五种组合：linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64，其他组合直接报错（install）。此外还有两个值得注意的探测逻辑：

musl 检测（install）：Linux 下若存在 /etc/alpine-release，或 ldd --version 输出含 "musl"，产物名追加 -musl 后缀。这意味着 Alpine 等 musl 发行版会自动拿到静态链接版本。
baseline 变体（install）：x64 平台上若 CPU 不支持 AVX2（Linux 读 /proc/cpuinfo、macOS 读 sysctl hw.optional.avx2_0、Windows 通过 PowerShell 查询处理器特性），产物名追加 -baseline，为老 CPU 提供不带 AVX2 指令集的构建。
macOS Rosetta 纠偏（install）：在 Rosetta 2 下运行的 x64 shell 会被识别为 arm64，从而下载 Apple Silicon 原生二进制。
架构名归一化：aarch64 映射为 arm64，x86_64 映射为 x64；Linux 产物为 .tar.gz，其余为 .zip。

下载完成后，脚本会把二进制放入安装目录并 chmod 755（install）；若目标版本已安装则直接退出（check_version，install）。

PATH 修改与 CI 集成

脚本会根据当前 shell（fish / zsh / bash / ash / sh）选择配置文件，将安装目录追加进 $PATH，且写入前会先 grep -Fxq 去重，避免重复行（install）。若未找到配置文件，脚本会提示手动执行：

export PATH=$INSTALL_DIR:$PATH

在 GitHub Actions 环境中，脚本检测到 GITHUB_ACTIONS=true 时会直接把安装目录追加到 $GITHUB_PATH，无需依赖 shell 配置文件（install）。

二、安装目录的确定：文档优先级 vs 脚本实际行为

README 给出安装路径的四级优先级：

$OPENCODE_INSTALL_DIR - 自定义安装目录
$XDG_BIN_DIR - 符合 XDG Base Directory Specification 的路径
$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 脚本中，安装目录被硬编码为：

INSTALL_DIR=$HOME/.opencode/bin
mkdir -p "$INSTALL_DIR"

也就是说，就本仓库提交版本而言，$OPENCODE_INSTALL_DIR、$XDG_BIN_DIR、$HOME/bin 这几级优先级尚未在脚本中实现，所有安装默认落在 ~/.opencode/bin。如果你在部署时依赖文档描述的目录优先级，建议以线上实际部署的脚本为准，或直接用包管理器（brew / scoop / npm）规避该问题；$HOME/.opencode/bin 这一默认回退行为则与文档一致，可以确认。

三、桌面应用（Beta）：各平台安装包与安装渠道

OpenCode 同时提供桌面应用（Beta 阶段），可从官方 releases 页面下载。README 列出的各平台产物如下：

平台	下载文件
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`

包管理器渠道（README）：

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

仓库内可以印证桌面应用是一个完整的 Electron 工程：packages/desktop/package.json 定义了应用本身，packages/desktop/electron-builder.config.ts 即 electron-builder 打包配置（生成上表中的 dmg / exe / deb / rpm 等产物），packages/desktop/src 下按 main / preload / renderer 三层组织代码，图标资源位于 packages/desktop/icons（按 beta / dev / prod 三套环境区分），构建前预处理脚本在 packages/desktop/scripts（如 prebuild.ts、copy-bundles.ts）。Linux 容器化构建则由 packages/containers/tauri-linux 提供 Dockerfile 支持。

四、内置 Agent：build、plan 与 general

这是 README 中最核心的功能说明（README）：

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

TUI 中通过 Tab 键在 Agent 间切换，这一行为在源码中有明确对应：TUI 的键位配置把 tab 绑定为 agent_cycle（下一个 Agent）、shift+tab 绑定为 agent_cycle_reverse（上一个 Agent），见 packages/tui/src/config/keybind.ts。

源码视角：三个 Agent 的权限边界

Agent 的完整定义位于 packages/opencode/src/agent/agent.ts，与 README 的描述可以逐条对上：

1. build（默认主 Agent）（agent.ts）

build: {
  name: "build",
  description: "The default agent. Executes tools based on configured permissions.",
  permission: Permission.merge(
    defaults,
    Permission.fromConfig({
      question: "allow",
      plan_enter: "allow",
    }),
    user,
  ),
  mode: "primary",
  native: true,
}

mode: "primary" 表明它是可在 TUI 中用 Tab 切换的主 Agent；权限为"默认权限 + 允许提问 + 允许进入 plan 模式"，再叠加用户在配置中自定义的 permission。默认权限本身也值得注意（agent.ts）：整体 * 允许，但 doom_loop（死循环检测）会询问、外部目录默认询问、*.env 与 *.env.* 文件读取会请求许可而 *.env.example 直接放行——与 Node 官方 gitignore 对 env 文件的处理模式保持一致。

2. plan（只读主 Agent）（agent.ts）

plan: {
  name: "plan",
  description: "Plan mode. Disallows all edit tools.",
  permission: Permission.merge(
    defaults,
    Permission.fromConfig({
      question: "allow",
      plan_exit: "allow",
      task: { general: "deny" },
      external_directory: {
        [path.join(Global.Path.data, "plans", "*")]: "allow",
      },
      edit: {
        "*": "deny",
        [path.join(".opencode", "plans", "*.md")]: "allow",
        [path.relative(ctx.worktree, path.join(Global.Path.data, path.join("plans", "*.md")))]: "allow",
      },
    }),
    user,
  ),
  mode: "primary",
  native: true,
}

这里精确落实了 README 的三句话：edit: { "*": "deny" } 对应"默认拒绝文件编辑"（但为 plans 目录下的 .md 计划文件开白名单，允许 plan Agent 把计划落盘）；task: { general: "deny" } 意味着 plan 模式下不能派生 general 子 Agent；plan_exit: "allow" 则允许从 plan 模式切回 build 模式，对应 TUI 中"分析完毕、开始动手"的工作流。

3. general（通用子 Agent）（agent.ts）

general: {
  name: "general",
  description: `General-purpose agent for researching complex questions and executing multi-step tasks. Use this agent to execute multiple units of work in parallel.`,
  permission: Permission.merge(
    defaults,
    Permission.fromConfig({
      todowrite: "deny",
    }),
    user,
  ),
  options: {},
  mode: "subagent",
  native: true,
}

mode: "subagent" 表明它不进入 Tab 切换序列，而是作为内部子 Agent 被调度，这解释了 README 中"内部使用、可用 @general 调用"的表述；它对 todowrite 工具设为 deny，即子 Agent 不修改任务清单，避免嵌套任务互相干扰。

4. 顺带一提：源码中还有两个 README 未提及的 Agent。同一文件里还定义了 explore（只读的代码库快速探索子 Agent，仅放行 grep/glob/list/bash/read 等只读工具，agent.ts）以及隐藏的 compaction、title 等系统 Agent（hidden: true，用于会话压缩与自动命名标题）。从源码结构看，这些 Agent 属于平台内置能力，README 只挑选了用户感知最强的三个来介绍；如果你要理解 OpenCode 的 Agent 全貌，packages/opencode/src/agent/agent.ts 是权威出处。

默认 Agent 的选择：源码中排序逻辑显示，default_agent 配置项可改变默认 Agent，未配置时回退到 build（agent.ts）。

自定义 Agent 与扩展

README 将更深入的 Agent 话题（自定义 Agent、model 指定、prompt 定制等）指向官方文档站。在仓库中，Agent 定义会经过配置层（packages/opencode/src/config）与插件体系（packages/core/src/plugin）加载，权限模型由 packages/core/src/permission 与 packages/opencode/src/permission 共同实现；子 Agent 的权限裁剪逻辑见 packages/opencode/src/agent/subagent-permissions.ts。

五、贡献与命名约定

README 最后还有两条社区约定，值得二次开发者和插件作者留意（README）：

向 OpenCode 提 Pull Request 前，先阅读 CONTRIBUTING.md 中的贡献流程；
如果你的项目与 OpenCode 相关、且名称中包含 "opencode"（如 "opencode-dashboard"、"opencode-mobile"），请在 README 中明确声明该项目并非由 OpenCode 团队制作、与其无任何隶属关系。

六、小结：一张表看懂 OpenCode 的安装与 Agent 体系

维度	关键事实	仓库证据
快速安装	`curl -fsSL https://opencode.ai/install \| bash`，默认装到 `~/.opencode/bin`	install
版本锁定	`bash -s -- --version <ver>`，带 release 存在性校验	install
平台矩阵	linux/darwin x64/arm64 + windows x64；musl 与 baseline 自动识别	install
桌面应用	Beta，dmg / exe / deb / rpm / AppImage	README、packages/desktop
主 Agent	build（默认，全权限）、plan（只读 + 计划文件白名单），Tab 切换	agent.ts
子 Agent	general（`@general` 调用）、explore 等	agent.ts