OpenCode 开源编码代理：安装通道、目录优先级与 build / plan / general Agent 体系详解

OpenCode 开源编码代理：安装通道、目录优先级与 build / plan / general Agent 体系详解

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode

本文基于 OpenCode 仓库根目录的丹麦语版 README（README.da.md）及其对应的真实实现展开，覆盖三条主线：OpenCode 的完整安装通道（一键脚本与各包管理器）、安装脚本的目录优先级与 PATH 处理逻辑、以及内置 build / plan 双 Agent 加 general 子代理的权限模型。读完后你可以独立完成安装与升级、理解二进制落盘位置，并能从源码层面解释每个 Agent 的权限边界。

1. OpenCode 是什么

OpenCode 自称 “The open source AI-kodeagent”（开源 AI 编码代理）。它的主入口是一个终端 TUI：在项目目录中运行opencode命令即可进入交互式编码会话；同时项目提供了一个处于 BETA 阶段的桌面应用。本仓库是多包 monorepo，核心实现位于 packages/opencode 包中，本文涉及的关键证据包括：

• 安装脚本：install（仓库根目录的 bash 脚本）
• Agent 定义：packages/opencode/src/agent/agent.ts
• Agent 行为测试：packages/opencode/test/agent/agent.test.ts
• 卸载命令：packages/opencode/src/cli/cmd/uninstall.ts

2. 安装方式

README 提供了“YOLO”式一键安装与各包管理器安装两大类通道，以下完整继承原文档内容。

2.1 一键安装脚本

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

仓库根目录的 install 脚本即该类安装器的参考实现。从脚本的usage()帮助文本（install#L10-L27）可以看到它实际支持的参数：

对应的调用形态为：

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

脚本内部还有几个值得注意的健壮性设计（均为源码可确认事实）：

• 平台矩阵：仅接受linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64五种组合，其余直接报错退出（install#L103-L110）。
• Rosetta 检测：在 Intel 转译运行的 macOS（sysctl.proc_translated = 1）上会自动改用 arm64 二进制。
• AVX2 baseline 检测：x64 平台上若 CPU 不支持 AVX2（Linux 查/proc/cpuinfo、macOS 查hw.optional.avx2_0、Windows 通过 PowerShell 调IsProcessorFeaturePresent(40)），下载目标会自动追加-baseline后缀。
• musl 检测：Alpine 或ldd --version输出含 musl 的 Linux 会下载-musl变体。
• 版本校验：check_version()会先执行已安装的opencode --version，若目标版本已安装则直接退出（install#L221-L235）；指定版本时还会先对 release 做 HEAD 请求，404 则报 “Release vX not found”。
• PATH 自动写入：脚本按当前 shell（fish / zsh / bash / ash / sh）选择对应配置文件追加 PATH 语句，已有相同内容则跳过；在 GitHub Actions 环境中会额外写入$GITHUB_PATH（install#L362-L444）。

2.2 包管理器安装

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 分支

提示（原文档 TIP）：安装前先移除 0.1.x 之前的旧版本。仓库中的卸载命令 packages/opencode/src/cli/cmd/uninstall.ts 会清理.opencode/bin相关的 PATH 配置行（包括 bash 的export PATH=、fish 的fish_add_path以及# opencode标记注释），可作为移除旧安装的参考实现。

2.3 桌面应用（BETA）

OpenCode 也以桌面应用形式发布，可从 releases 页或官网下载页获取。各平台安装包命名如下（原文档表格）：

包管理器渠道：

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

桌面端源码位于 packages/desktop，其主进程在 WSL 场景下还会探测$HOME/.opencode/bin/opencode这一典型安装路径（见 packages/desktop/src/main/wsl/runtime.ts），与下文安装目录的默认 fallback 相互印证。

3. 安装目录的优先级

README 指出安装脚本按以下顺序确定安装路径：

1. $OPENCODE_INSTALL_DIR—— 自定义安装目录
2. $XDG_BIN_DIR—— 遵循 XDG Base Directory Specification 的目录
3. $HOME/bin—— 标准用户 bin 目录（若存在或可创建）
4. $HOME/.opencode/bin—— 默认 fallback

配合环境变量的用法示例（原文档）：

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（INSTALL_DIR=$HOME/.opencode/bin并mkdir -p）。因此上述四级优先级描述的是官方https://opencode.ai/install托管安装器的行为约定，而本仓库脚本可确认的是默认落盘位置、PATH 写入逻辑与 GITHUB_PATH 处理。若你在 CI 或受限环境中安装，以$HOME/.opencode/bin作为二进制落盘位置做后续引用（如桌面端 WSL 探测逻辑）是最稳妥的假设。

4. Agent 体系：build、plan 与 general

README 描述了 OpenCode 的两个内置 Agent——可在会话中用Tab键切换——以及一个内部子代理：

• build—— 默认 Agent，拥有完整的开发工作权限
• plan—— 只读 Agent，用于分析与代码探索
  • 默认拒绝文件编辑
  • 执行 bash 命令前会请求许可
  • 适合探索陌生代码库或规划改动
• general—— 面向复杂搜索与多步任务的子代理，内部使用，可通过在消息中@general调用

这段描述与源码高度吻合。三个原生 Agent 在 packages/opencode/src/agent/agent.ts 中以mode: "primary"（build、plan）和mode: "subagent"（general）的方式注册，其权限由Permission.merge分层合并：

4.1 build：默认 Agent

build 在默认权限之上放开了两个动作（agent.ts#L141-L155）：

• question: "allow"—— 允许 Agent 主动向用户提问
• plan_enter: "allow"—— 允许进入 plan 模式

默认权限基线（agent.ts#L119-L136）本身已包含若干安全约束：doom_loop: "ask"、外部目录写入ask、读取*.env/*.env.*需要确认（*.env.example除外）、question默认deny、plan_enter/plan_exit默认deny。build 之所以“全权限”，是相对这些收紧项的放开，而非无任何约束。用户配置（cfg.permission）始终通过Permission.merge叠加在最上层，可覆盖上述默认值。

4.2 plan：写保护 Agent

plan Agent 的权限覆盖（agent.ts#L156-L181）精确对应 README 的“拒绝文件编辑”描述：

• edit: { "*": "deny" }—— 拒绝一切编辑；
• 但允许写两个“计划文件”例外路径：.opencode/plans/*.md与全局数据目录下的plans/*.md，即 plan 模式可以落盘规划文档，只是不能改代码；
• task: { general: "deny" }—— plan 模式下默认禁止调用 general 子代理；
• plan_exit: "allow"—— 允许退出 plan 模式返回 build。

测试用例直接验证了这些行为：packages/opencode/test/agent/agent.test.ts 断言 “plan agent denies the general subagent by default”（Permission.evaluate("task", "general", plan.permission)返回deny），并在特定规则集下返回allow。

4.3 general：多步子代理

general 的定义（agent.ts#L182-L195）描述为 “General-purpose agent for researching complex questions and executing multi-step tasks”，其唯一额外收紧项是todowrite: "deny"（子代理不写 TODO 清单）。从源码结构看，CLI 的 run 命令在执行子任务时默认subagent_type即general（见 packages/opencode/src/cli/cmd/run/tool.ts），这与 README “通过@general在消息中调用” 的说明一致。此外源码中还存在一个未在 README 展开的explore只读搜索子代理（agent.ts#L196-L218），其权限仅开放 grep / glob / list / read / web 检索等只读工具，可作为 plan 模式探索场景的补充参考。

5. 贡献与衍生项目命名约定

README 最后给出两条社区规范：

• 贡献：提交 pull request 前应先阅读 CONTRIBUTING.md。
• 衍生项目声明：如果你的项目名包含 “opencode”（例如 “opencode-dashboard”、“opencode-mobile”），但并非 OpenCode 团队开发，应在你的 README 中明确注明该项目与 OpenCode 团队无隶属关系。

6. 延伸阅读路径

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode