OpenCode 开源编码代理：安装方式、安装目录优先级与 build/plan/general 内置 Agent 机制详解

OpenCode 是一个开源的 AI 编码代理（AI coding agent），本文以仓库中的 README.no.md（挪威语版 README）为骨架，系统讲解它的全部安装渠道（一键脚本与各类包管理器）、BETA 版桌面应用、安装脚本的目录优先级规则，以及 build、plan、general 三类内置 Agent 的职责划分与权限边界。读完后，你可以按官方推荐方式正确安装 OpenCode，理解安装产物落在哪个目录、PATH 如何被修改，并能从源码层面看懂默认 Agent 选择与 plan 模式"只读"约束是如何实现的。

一、项目定位

README.no.md 开篇给出的定位只有一句话："AI-kodeagent med åpen kildekode"（拥有开源代码的 AI 编码代理）。仓库通过徽章显示 npm 包 opencode-ai 的版本与发布流水线状态，并提供了 20 种语言的 README 互链（README.md、README.zh.md、README.ja.md 等），方便不同语言的开发者查阅同一套内容。本文对应的中文读者，其内容与英文版 README.md 完全等价。

二、安装方式：一键脚本与包管理器

README.no.md 的"Installasjon"（安装）章节给出了两套途径：

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

# Pakkehåndterere
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 公式，更新较少）
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 分支

需要注意两条官方提示：

1. TIP 提示：安装前应先移除 0.1.x 之前的旧版本（原文 "Fjern versjoner eldre enn 0.1.x før du installerer"）。
2. 渠道优先级：macOS/Linux 官方推荐 anomalyco/tap/opencode 这个 tap 版本，因为它"始终保持最新"；brew install opencode 走的官方公式更新频率较低。

安装脚本源码解析

一键脚本 curl -fsSL https://opencode.ai/install | bash 对应的脚本源码就保存在仓库根目录 install 中，从中可以确认若干 README 未展开的实现细节：

命令行参数（install#L10-L27）：

参数	作用
-h, --help	显示帮助信息
-v, --version <version>	安装指定版本（例如 bash -s -- --version 1.0.180）
-b, --binary <path>	从本地已有二进制安装，跳过全部下载与检测逻辑
--no-modify-path	不修改 shell 配置文件（.zshrc、.bashrc 等）

平台与架构检测（install#L79-L110）：脚本通过 uname -s/uname -m 识别平台，仅支持 linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64 五种组合，其余组合直接报错退出。此外还有两个精妙的细节：

• Rosetta 检测：在 darwin-x64 上，脚本会用 sysctl -n sysctl.proc_translated 判断当前是否运行在 Rosetta 翻译层，若是则把架构改回 arm64 下载（install#L95-L100）。
• baseline 回退：x64 环境下若 CPU 不支持 AVX2（Linux 检查 /proc/cpuinfo、macOS 检查 hw.optional.avx2_0、Windows 通过 PowerShell 调用 IsProcessorFeaturePresent(40)），下载目标会自动追加 -baseline 后缀（install#L130-L163）。Linux 下还会识别 musl libc 环境（Alpine 的 /etc/alpine-release 或 ldd --version 输出）并追加 -musl 后缀。

版本获取与下载（install#L183-L204）：未指定版本时从 GitHub releases 的 latest 下载，并从 GitHub API 解析 tag_name 得到具体版本号；指定 -v 时先通过 HTTP 状态码校验该 release 是否存在（404 则报错并提示可用 release 列表），避免下载不存在的版本。

PATH 写入逻辑（install#L362-L444）：脚本按 $SHELL 判断当前 shell（fish/zsh/bash/ash/sh 各有配置文件候选列表），找到第一个存在的配置文件后追加 export PATH=<安装目录>:$PATH（fish 用 fish_add_path），且已存在该命令或不可写时会跳过写入并打印手动添加提示。在 CI 环境中（GITHUB_ACTIONS=true），它还会把安装目录写入 $GITHUB_PATH。

安装目录优先级

README.no.md 的"Installasjonsmappe"（安装目录）章节明确列出了脚本决定安装路径的四级优先级：

1. $OPENCODE_INSTALL_DIR —— 自定义安装目录
2. $XDG_BIN_DIR —— 符合 XDG Base Directory Specification 的路径
3. $HOME/bin —— 标准用户二进制目录（若已存在或可创建）
4. $HOME/.opencode/bin —— 默认兜底

原文给出的两个示例：

# Eksempler
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 优先级逻辑——从源码结构看，README 描述的是线上 opencode.ai/install 分发版的目标行为，仓库内脚本可能是较早期或用于别处的副本，以线上脚本实际表现为准。

三、桌面应用（BETA）

README.no.md 指出 OpenCode 还提供桌面应用（标记为 BETA），可从 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 (Homebrew)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop

仓库中桌面端对应 packages/desktop（Electron 工程，含 src/main、src/preload、src/renderer），构建配置见 electron-builder.config.ts，图标资源分 beta/dev/prod 三套存放于 packages/desktop/icons，与 BETA 阶段的产物命名相互印证。

四、内置 Agents：build、plan 与 general

这是 README.no.md 的核心技术章节（"Agents"）。原文说明：

OpenCode 有两个内置 agents，可以用 Tab 键切换：

• build —— 默认，拥有完全访问权限的开发代理
• plan —— 只读代理，用于分析与代码探索
  • 默认拒绝文件修改
  • 执行 bash 命令前会请求许可
  • 适合探索陌生代码库或规划变更

另外还有一个 general 子代理，用于复杂搜索与多步骤任务，供内部使用，可在消息中通过 @general 调用。

源码中的内置 Agent 定义

上述描述可以在 packages/opencode/src/agent/agent.ts#L140-L195 中逐条验证。内置 Agent 以 mode 字段区分角色：primary（可被 Tab 切换的主代理）与 subagent（只能被调用的子代理）：

build（默认，mode: primary）：

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,
},

build 允许 question 工具与进入 plan 模式（plan_enter: "allow"），权限基线 defaults 是"全允许"（"*": "allow"）叠加若干安全例外（如读取 *.env 文件需要询问、doom_loop 需要询问等，见 agent.ts#L119-L136）。

plan（只读，mode: primary）：

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",
        ...
      },
    }),
    user,
  ),
  mode: "primary",
  native: true,
},

可以确认 plan 模式的行为边界：edit: { "*": "deny" } 默认拒绝一切文件编辑，仅放行 .opencode/plans/*.md 计划文件的写入；task: { general: "deny" } 禁止它派生 general 子任务；plan_exit: "allow" 则允许它请求退出 plan 模式。这与 README "默认拒绝文件修改、执行 bash 前询问"的描述一致——bash 走的是 defaults 中的询问基线。相关行为还有专门测试 plan-mode-subagent-bypass.test.ts 覆盖。

general（subagent）：

general: {
  name: "general",
  description: `General-purpose agent for researching complex questions and executing multi-step tasks. ...`,
  permission: Permission.merge(defaults, Permission.fromConfig({ todowrite: "deny" }), user),
  mode: "subagent",
  native: true,
},

general 被定义为 mode: "subagent"，即不出现在 Tab 切换列表里、供内部任务派生使用，且在消息中可通过 @general 显式调用；它还显式禁用了 todowrite 工具，避免子代理写 todo 清单。

除三者外，源码中还内置了 explore（面向代码库快速检索的只读子代理，仅允许 grep/glob/list/bash/read 等只读类工具）以及 compaction、title、summary 等 hidden: true 的后台辅助代理（agent.ts#L196-L265）。

默认 Agent 的选择逻辑

Tab 切换候选的过滤与默认值回退逻辑在两处可见：

1. v2 状态服务 packages/core/src/agent.ts#L67-L79：selectable() 只保留 mode !== "subagent" 且未 hidden 的代理；默认值优先取用户配置的 default，其次回退到 build，最后回退到任意第一个可选项。defaultID 常量即为 ID.make("build")（agent.ts#L10）。
2. v1 Agent 服务 packages/opencode/src/agent/agent.ts 中的 Info schema 定义了 Agent 的完整字段（mode: "subagent" | "primary" | "all"、permission、model、prompt 等），说明用户可以在配置中覆盖这些内置代理或定义新代理——这正是 README "Dokumentasjon" 章节指向文档站配置文档的原因。

测试用例 agent.test.ts 中对 mode: "subagent" 的多种断言（约 426-455 行）验证了子代理在权限继承与调用路径上的行为边界。

五、贡献与命名规范

README.no.md 最后还有两条治理性说明：

• 贡献：提交 PR 前先阅读 CONTRIBUTING.md（原文链接的相对路径 ./CONTRIBUTING.md，即仓库根目录下的该文件）。
• 基于 OpenCode 构建：如果你的项目与 OpenCode 相关且在名称中使用 "opencode"（例如 "opencode-dashboard"、"opencode-mobile"），必须在你的 README 中声明它并非由 OpenCode 团队构建、与官方无任何关联。

六、小结

对照 README.no.md 的完整脉络，本文覆盖并扩充了全部四个技术章节：

README 章节	本文补充的仓库证据
Installasjon（安装）	install 脚本的参数、平台/架构/Rosetta/AVX2/musl 检测逻辑
Installasjonsmappe（安装目录）	四级环境变量优先级的出处与仓库脚本现状的差异说明
Desktop-app (BETA)	packages/desktop 工程结构与 electron-builder 配置
Agents	packages/opencode/src/agent/agent.ts#L140-L195 中 build/plan/general 的权限矩阵、默认选择回退链与测试用例

按推荐路径（macOS/Linux 用 brew install anomalyco/tap/opencode，Windows 用 Scoop/Chocolatey）安装后，进入项目目录运行 opencode 即可启动 TUI；用 Tab 在 build 与 plan 之间切换，在消息中用 @general 调起通用子代理，这三点构成日常使用 OpenCode 的最小操作集。