OpenCode 开源 AI 编码代理：安装方式、安装目录优先级与内置 Agent 体系全解析

2026-09-05 14:07:34作者：宣利权Counsellor

本文以 OpenCode 项目的官方说明文档为核心，系统梳理这个开源 AI 编码代理（open source coding agent）的完整落地路径：从一行 curl 命令的裸装、十余种包管理器渠道，到 Beta 版桌面应用的各平台产物，再到 build / plan / general 三套内置 Agent 的权限模型。读完本文，你将掌握 OpenCode 的全部安装方式与安装目录优先级机制，并能结合仓库源码理解其安装脚本的平台探测逻辑与 Agent 权限配置的实现细节。

项目定位

OpenCode 是一个开源的 AI 编码代理，以终端 TUI（终端用户界面）为主要交互形态，通过包名 opencode-ai 发布到 npm，同时提供桌面端应用。从仓库结构看，这是一个以根 package.json 组织的 monorepo：核心 CLI 位于 packages/opencode，此外还有 TUI（packages/tui）、桌面端（packages/desktop）、Web 应用（packages/app）、LLM 协议层（packages/llm）等模块；本地开发时可通过根目录脚本 bun run dev 直接以源码方式运行核心 CLI（对应 bun run --cwd packages/opencode src/index.ts）。

官方 README 提供 20 种语言版本（含英、简中、繁中、法语等），内容一致；本文基于其中的说明文档，并结合仓库源码做纵深补充。

安装方式

一键脚本安装（YOLO 模式）

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

这是文档标注的 "YOLO" 安装方式，适合追求最快捷径的用户。

TIP：安装前请删除 0.1.x 之前的旧版本，避免新旧二进制冲突。

包管理器渠道

官方文档列出了覆盖主流平台的全部包管理器渠道：

npm i -g opencode-ai@latest        # 或使用 bun / pnpm / yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS 和 Linux（官方 tap，推荐，更新最快）
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           # Nix；亦可使用 flake 追踪 dev 分支最新构建

几点值得注意：

macOS/Linux 下 Homebrew 提供两条通道：anomalyco/tap/opencode 是项目自有 tap，更新最及时，官方推荐；brew install opencode 走社区官方公式，更新周期更长。
Arch 用户可按需选择 Stable 源的 opencode（pacman）或 AUR 的 opencode-bin（paru，最新版）。
Nix 用户除 nix run nixpkgs#opencode 外，还可以用 flake 方式直接指向 dev 分支的最新构建。仓库中 nix/opencode.nix 即为项目维护的 Nix 派生定义，它基于 Bun 打包核心包（bun --bun ./script/build.ts --single），并注入 OPENCODE_CHANNEL=prod、OPENCODE_VERSION 等构建环境变量——这说明 nixpkgs 中的 opencode 包与仓库构建流水线是同源可复现的。

安装脚本源码级解读

仓库根目录保留了安装脚本本体 install，与 curl | bash 下发的是同一套逻辑，可以直接阅读验证其完整行为：

支持的命令行参数（见 install#L10-L27）：

参数	作用
`-h, --help`	显示帮助信息
`-v, --version <版本>`	安装指定版本，如 `curl -fsSL https://opencode.ai/install \| bash -s -- --version 1.0.180`
`-b, --binary <路径>`	跳过全部下载与平台探测逻辑，直接从本地二进制安装
`--no-modify-path`	不修改 shell 配置文件（`.zshrc`、`.bashrc` 等），适合 CI 或自管 PATH 的场景

平台与 CPU 特性探测（install#L79-L166）：

通过 uname -s / uname -m 归一化出 darwin/linux/windows × x64/arm64 五种组合，其余组合直接报错退出；
macOS 上会通过 sysctl.proc_translated 识别 Rosetta 转译环境，自动选择 arm64 产物；
Linux 下检测 musl 工具链（Alpine 的 /etc/alpine-release 或 ldd --version 输出），产物后缀加 -musl；
x64 平台还会探测 CPU 是否支持 AVX2（Linux 查 /proc/cpuinfo、macOS 查 hw.optional.avx2_0、Windows 通过 PowerShell 调 IsProcessorFeaturePresent），不支持时回退到 -baseline 产物，保证老 CPU 也能运行；
Linux 打包为 .tar.gz，其余平台为 .zip，并分别校验 tar / unzip 是否可用。

版本与下载（install#L183-L204）：未指定版本时拉取 releases 的 latest 产物并解析 tag_name 得到版本号；指定版本时先对 release tag 发起 HEAD 请求，404 立即报错并提示可用版本列表，避免无效下载。

PATH 自动配置（install#L362-L444）：脚本按当前 $SHELL 选择配置文件（zsh → .zshrc/.zshenv、bash → .bashrc 等、fish → config.fish），写入前先用 grep -Fxq 去重，不可写时降级为打印手动追加命令；在 GitHub Actions 中还会把安装目录追加进 $GITHUB_PATH，方便 CI 直接使用。

需要说明的是：README 描述的"安装目录优先级"（下一节）面向官方 install 端点下发的脚本；仓库内这份脚本源码中，默认安装目录写死为 $HOME/.opencode/bin（install#L68），两者属于同一机制的不同发布形态。

安装目录优先级

官方安装脚本在安装目录上遵循如下优先级顺序（从高到低）：

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

文档给出的两个示例：

# 示例一：安装到系统级目录
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

# 示例二：安装到 XDG 用户 bin 目录
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

这一优先级设计兼顾了三类用户：CI/管理员可通过 OPENCODE_INSTALL_DIR 完全接管落盘位置；遵循 XDG 规范的发行版用户走 $XDG_BIN_DIR；其余场景安全回退到用户主目录下的 .opencode/bin，无需 root 权限。

桌面应用（BETA）

除终端形态外，OpenCode 还提供 Beta 版桌面应用，可从 GitHub releases 页面或官网下载页获取，产物矩阵如下：

平台	下载产物
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 与 Windows 也可走包管理器：

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

桌面端由 monorepo 中的 packages/desktop 承载，基于 electron-builder 构建，构建产物命名（mac-arm64 / mac-x64 / windows-x64 及 Linux 三格式）与上表严格对应，仓库内还有 packages/desktop/scripts/ 下的 finalize-latest-json.ts、finalize-latest-yml.ts 等脚本用于生成 latest 发布元信息。

内置 Agent 体系

OpenCode 内置了可用 Tab 键切换的两个主 Agent，并额外提供一个子 Agent：

build — 默认 Agent，拥有完整工具访问权限，面向日常开发工作；
plan — 只读 Agent，面向代码分析与探索：
- 默认拒绝一切文件修改；
- 执行 bash 命令前必须先征求用户许可；
- 适合探索陌生代码库或预先规划改动方案；
general（子 Agent）— 面向复杂检索与多步骤任务，由主 Agent 内部调用，也可以在消息中通过 @general 显式唤起。

源码中的权限模型

三个 Agent 的定义可以在 packages/opencode/src/agent/agent.ts 中找到，其行为由 mode（primary / subagent / all）与 permission 规则表共同决定：

build（mode: "primary"）：以默认权限表为基线，显式放开 question 与 plan_enter，是 Tab 切换的默认落点；
plan（mode: "primary"）：在 edit 权限上采用 "*": "deny" 全局拒绝策略，仅白名单放行 .opencode/plans/*.md 及数据目录下的计划文件——"只读"并非简单地不注册编辑工具，而是靠 deny-all + 精确放行的权限规则实现的；同时它对 task: general 设为 deny，意味着 plan 模式下不会递归派生 general 子 Agent；
general（mode: "subagent"）：描述为"用于研究复杂问题并执行多步任务"，权限上仅额外 deny 了 todowrite。

从源码结构看，agent.ts 中还注册了 README 未逐一展开的内置 Agent：面向代码库探索的只读 explore 子 Agent（仅放行 grep / glob / list / read 等检索类工具），以及 compaction、title、summary 等 hidden: true 的系统级 Agent，负责上下文压缩、会话标题生成与摘要——它们同样走同一套 mode + permission 机制，只是不对用户暴露。此外，用户配置中的 cfg.agent 覆盖层可以在 agent.ts#L267-L294 处对任意内置 Agent 改写 model、prompt、permission 等字段，甚至用 disable: true 整体移除。

关于各 Agent 的更多配置细节，请查阅 OpenCode 官方文档站的 agents 章节。

配置与生态

配置文档：OpenCode 的完整配置方式（模型、权限、MCP 等）以官方文档站为准；本仓库 packages/docs 与 packages/web 即文档站与官网的源码，其中 docs/essentials/ 目录收录了 settings、navigation、code 等入门主题，可作为配置项的参照。
贡献指南：向项目提交 PR 前，请先阅读 CONTRIBUTING.md。
命名规范：如果你基于 OpenCode 生态做二次项目，且项目名中使用了 "opencode"（例如 "opencode-dashboard"、"opencode-mobile"），官方要求在你的 README 中明确注明：该项目并非由 OpenCode 团队构建，与其没有任何隶属关系。
社区：项目通过官方 Discord 社区与 X（原 Twitter）账号维持交流。

小结

OpenCode 的安装面覆盖了 curl 脚本、npm/bun、Homebrew 双通道、Scoop/Chocolatey、pacman/AUR、mise 与 Nix 等几乎全部主流分发渠道，且安装脚本在 musl 工具链、Rosetta、AVX2 等边界场景上都有显式处理，安装目录优先级则以 $OPENCODE_INSTALL_DIR → $XDG_BIN_DIR → $HOME/bin → $HOME/.opencode/bin 的顺序兼顾管理员、XDG 用户与普通用户三类场景。运行层面，build / plan / general 三 Agent 通过统一的 mode + permission 权限表实现"默认开发—只读分析—多步任务"的分工，源码中 deny-all + 白名单放行的写法（如 plan 仅允许写 plans/*.md）也为自定义 Agent 权限提供了清晰的参考范式。