OpenCode 安装指南：多平台安装方式、安装目录策略与 build/plan 双代理体系解析

2026-09-04 13:00:22作者：咎岭娴Homer

OpenCode 是一个开源的 AI 编码代理（AI coding agent），既提供终端 TUI 界面，也提供桌面应用形态。本篇围绕仓库中的 README（及其孟加拉语版本 README.bn.md）展开，完整覆盖官方推荐的多种安装方式、安装脚本的目录选择优先级、桌面应用（BETA）的下载渠道，并结合仓库源码深入解析 OpenCode 内置的 build、plan、general 三类代理的权限差异，帮助你在任意平台上完成部署并正确理解各代理的行为边界。

一、安装方式总览

官方 README 给出了一条"一步到位"的安装脚本和一系列包管理器安装路径。安装前请注意官方提示：先移除 0.1.x 之前的旧版本，再执行安装，以避免旧版二进制与新配置不兼容。

1. 一键安装脚本

# YOLO
curl -fsSL https://opencode.ai/install | bash

该脚本对应的仓库内实现见 install 脚本。从源码结构看，这份 Bash 脚本具备以下能力，与 README 描述的"一条命令装好"一致：

平台探测：通过 uname -s / uname -m 识别系统（darwin / linux / windows，Windows 下兼容 MINGW/MSYS/CYGWIN）与架构（aarch64 归一为 arm64，x86_64 归一为 x64），并在 Apple Silicon 上运行 Rosetta 的 Intel 进程时自动切换为 arm64（install#L79-L100）；
特殊构建目标识别：Linux 上检测 musl（Alpine 或 ldd 输出）追加 -musl 后缀；x64 机器若缺少 AVX2 指令集（检查 /proc/cpuinfo、macOS 的 sysctl、Windows 的 PowerShell IsProcessorFeaturePresent）则追加 -baseline 后缀，确保在不支持 AVX2 的 CPU 上也能运行（install#L117-L166）；
版本固定：支持 --version <版本> 安装指定版本、--binary <路径> 直接从本地二进制安装（跳过下载），以及 --no-modify-path 禁止脚本改动 shell 配置文件（install#L18-L26）；
PATH 自动配置：安装完成后按当前 shell（fish/zsh/bash/ash/sh）自动向对应配置文件（.zshrc、.bashrc、config.fish 等）追加 export PATH=...；在 GitHub Actions 环境中则写入 $GITHUB_PATH（install#L362-L444）。

2. 包管理器安装

# Package managers
npm i -g opencode-ai@latest        # or bun/pnpm/yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS and Linux (recommended, always up to date)
brew install opencode              # macOS and Linux (official brew formula, updated less)
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-bin               # Arch Linux (Latest from AUR)
mise use -g opencode               # Any OS
nix run nixpkgs#opencode           # or github:anomalyco/opencode for latest dev branch

各渠道的特点：

npm/bun/pnpm/yarn：安装 opencode-ai 包，适合已有 Node 生态环境的开发者；
Homebrew：官方推荐 anomalyco/tap/opencode（始终最新），brew install opencode 走官方 formula（更新频率较低）；
nix：nix run nixpkgs#opencode 安装 nixpkgs 收录版本，或使用 github:anomalyco/opencode 获取 dev 分支最新构建——仓库中 flake.nix 与 nix/opencode.nix 正是其 Nix 派生入口；
mise：跨平台版本管理器方式，任意操作系统可用。

二、桌面应用（BETA）

OpenCode 同时提供桌面应用形态，处于 BETA 阶段。官方说明可直接从 release 页面或 opencode.ai 的下载页获取安装包，各平台对应产物如下：

平台	下载产物
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/Electron 技术栈的 main、preload、renderer 三层结构，见 packages/desktop/src/main），图标与打包配置分别在 packages/desktop/icons 和 electron-builder.config.ts。上文截图即桌面应用的设置界面，可见其支持多语言界面切换（与仓库根目录下 19 种语言的 README 翻译体系相呼应）。

三、安装脚本的目录优先级

README 明确了安装脚本选择安装路径的优先级顺序：

$OPENCODE_INSTALL_DIR —— 自定义安装目录（最高优先级）；
$XDG_BIN_DIR —— 符合 XDG Base Directory Specification 的路径；
$HOME/bin —— 标准用户二进制目录（若已存在或可创建）；
$HOME/.opencode/bin —— 默认回退目录。

官方给出的示例：

# Examples
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 源码可以印证：脚本将安装目标目录常量默认设为 $HOME/.opencode/bin 并提前 mkdir -p（install#L68-L69），下载/解压后的二进制统一 mv 到该目录并 chmod 755（install#L327-L346）。README 中列出的 OPENCODE_INSTALL_DIR、XDG_BIN_DIR 等环境变量优先级属于线上安装脚本的完整行为说明，仓库内这份副本展示的是其最典型的默认回退路径逻辑。

四、内置代理：build / plan / general

这是 README 中最重要的使用知识：OpenCode 内置了两个可通过 Tab 键切换的主代理，另有一个用于复杂检索和多步任务的 general 子代理。

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

仓库源码 packages/opencode/src/agent/agent.ts 给出了这三者的精确权限定义，可以作为上表行为的实现级佐证：

// packages/opencode/src/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",
},
plan: {
  name: "plan",
  description: "Plan mode. Disallows all edit tools.",
  permission: Permission.merge(defaults, Permission.fromConfig({
    plan_exit: "allow",
    task: { general: "deny" },
    edit: {
      "*": "deny",                                        // 默认拒绝一切编辑
      [path.join(".opencode", "plans", "*.md")]: "allow", // 但允许写计划文件
    },
  }), user),
  mode: "primary",
},
general: {
  name: "general",
  description: "General-purpose agent for researching complex questions and executing multi-step tasks.",
  mode: "subagent",
},

从源码结构看，plan 代理的"只读"并非绝对：它虽然 edit: "*" deny，但显式放行了 .opencode/plans/*.md 等计划文件的写入（agent.ts#L171-L175），这意味着 plan 模式可以产出结构化的计划文档而不改动业务代码；同时它 task: general: "deny"，即 plan 模式下不能派生 general 子代理执行多步任务，这与"只读、仅分析"的定位完全吻合。而 general 的 mode: "subagent" 标注（agent.ts#L182-L195）解释了为何它在主界面不可用 Tab 切换、只能通过任务派生或 @general 触发。

此外，用户可以在配置中通过 cfg.agent 禁用某个原生代理（value.disable 时直接从代理表删除），或注册同名/自定义代理进行权限覆盖（agent.ts#L267-L279），这是 README 之外、由源码可确认的进阶能力。

五、贡献规范与命名约定

贡献：提交 Pull Request 之前，请先阅读 CONTRIBUTING.md。仓库自身的开发约定还集中在 AGENTS.md 与各包的 AGENTS.md（如 packages/opencode/AGENTS.md、packages/app/AGENTS.md），以及 specs/ 目录下的 v2 API、会话、工具等设计文档。
Building on OpenCode：如果你的项目名称中包含 "opencode"（例如 opencode-dashboard、opencode-mobile）且项目本身与 OpenCode 团队无隶属关系，README 要求在 README 中明确加注：该项目并非由 OpenCode 团队构建、与官方无任何关联。

六、延伸阅读

配置指南：README 指向官方 docs（opencode.ai/docs），仓库内可配合 packages/docs 目录下的 .mdx 文档源（quickstart.mdx、development.mdx 等）交叉阅读；
终端界面实现：packages/tui 是 OpenCode TUI 的主包（约 185 个源文件，含会话、代理切换等路由）；
服务端与协议：packages/server、packages/protocol、packages/schema 分别承载 HTTP 服务、线协议与数据 Schema，适合需要深入集成 OpenCode 的开发者继续下钻。