OpenCode 部署与使用指南:一键安装脚本、桌面应用分发与内置 Agent 体系

本文基于 OpenCode 仓库的官方 README(德语版 README.de.md,与英文版内容一致)展开,系统梳理 OpenCode 这个开源编码代理(AI Coding Agent)的完整部署路径:一键安装脚本的工作机制与参数、各平台包管理器安装方式、桌面应用(BETA)的分发产物,以及 build / plan / general 三类内置 Agent 的权限模型与切换方式。读完本文,你可以独立完成安装与升级,理解安装脚本的平台探测逻辑,并能从源码层面解释各内置 Agent 的权限边界与自定义 Agent 的配置入口。

项目定位与安装前准备

OpenCode 定位为"Der Open-Source KI-Coding-Agent"(开源 AI 编码代理),采用 MIT 协议发布,以终端 TUI 为主要交互形态,同时提供 BETA 阶段的桌面应用。当前仓库根目录的 package.json 显示其基于 Bun + TypeScript 的 monorepo 组织,核心可执行程序位于 packages/opencode,终端 UI 位于 packages/tui,桌面端位于 packages/desktop。

README 在安装章节前给出一条重要提示:

安装前请先移除 0.1.x 之前的旧版本,避免新旧版本共存导致的 PATH 冲突。

安装方式

1. 一键安装脚本(YOLO 方式)

README 给出的最简安装命令:

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

该命令对应仓库根目录的 install 脚本(460 行 Bash)。从源码看,脚本支持以下命令行选项(install#L16-L20):

-v, --version <version>   安装指定版本(例如 1.0.180)
-b, --binary <path>       从本地二进制文件安装,跳过下载与平台探测
    --no-modify-path      不修改 shell 配置文件(.zshrc、.bashrc 等)

指定版本安装的完整写法:

curl -fsSL https://opencode.ai/install | bash -s -- --version 1.0.180
# 或使用本地已编译的二进制
./install --binary /path/to/opencode

脚本内部的关键机制如下:

• 平台与架构探测(uname -s / uname -m):支持 linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64 五种组合,不支持的组合作为错误退出(install#L79-L110);
• Rosetta 检测:在 macOS x64 下通过 sysctl.proc_translated 判断是否运行在 Rosetta 转译环境中,若是则强制选择 arm64 产物(install#L95-L100);
• musl/glibc 区分:Linux 下通过 /etc/alpine-release 或 ldd --version 识别 musl 环境,产物后缀加 -musl(install#L117-L128);
• CPU 基线降级:x64 平台检测 AVX2 指令集(读取 /proc/cpuinfo、sysctl 或 PowerShell),无 AVX2 时选择 -baseline 变体,保证老 CPU 可运行(install#L130-L166);
• 版本解析:未指定版本时从 GitHub Releases API 获取 latest 标签;指定版本时会先做 404 校验,避免下载到不存在的 release(install#L183-L204);
• 幂等检查:若已安装的 opencode --version 与目标版本一致则直接退出,不重复下载(install#L221-L235);
• 下载与解压:交互式终端下用 curl --trace-ascii + FIFO 渲染实时进度条,Windows 或非 TTY 环境回退到标准 curl -#;Linux 解压 .tar.gz,其余平台解压 .zip(install#L267-L346);
• PATH 配置:根据 $SHELL 类型(fish/zsh/bash/ash/sh)写入对应的 rc 文件,追加 export PATH=$INSTALL_DIR:$PATH 或 fish 的 fish_add_path,已存在则跳过;在 GitHub Actions 环境还会把安装目录写入 $GITHUB_PATH(install#L362-L444)。

安装成功后,脚本末尾直接给出最小启动序列(install#L453-L456):

cd <project>   # 进入项目目录
opencode       # 运行命令

并提示 OpenCode 内置免费模型,开箱即可使用。

安装目录优先级

README 说明安装脚本按如下优先级决定安装路径:

1. $OPENCODE_INSTALL_DIR - 自定义安装目录
2. $XDG_BIN_DIR - XDG Base Directory Specification 规范路径
3. $HOME/bin - 用户标准 bin 目录(存在或可创建时)
4. $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 脚本将安装目录硬编码为 $HOME/.opencode/bin(install#L68),脚本内未见 OPENCODE_INSTALL_DIR / XDG_BIN_DIR 的处理分支。从源码结构看,官方站点实际分发的安装脚本可能是另行维护的版本,以上四级优先级应以 README 的文档描述作为目标行为理解。

2. 包管理器安装

README 列出的各平台安装命令:

# npm / bun / pnpm / yarn
npm i -g opencode-ai@latest

# Windows
scoop install opencode
choco install opencode

# macOS 与 Linux
brew install anomalyco/tap/opencode   # 官方 tap,更新更及时(推荐)
brew install opencode                  # Homebrew 官方 Formula,更新频率较低

# Arch Linux
sudo pacman -S opencode                # Stable
paru -S opencode-bin                   # AUR 最新版

# 跨平台
mise use -g opencode

# Nix
nix run nixpkgs#opencode               # 或 nixpkgs 源外指向 dev 分支以获取最新

其中 npm 包名为 opencode-ai,Nix 侧仓库还提供了 flake.nix 与 nix/opencode.nix 用于本地开发态构建。

桌面应用(BETA)

OpenCode 同时提供桌面应用,可从官方 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

包管理器方式:

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

桌面端基于 Electron 实现(packages/desktop/package.json 中依赖 electron 42.3.3 与 electron-vite),发布产物由 electron-builder.config.ts 生成,可以逐条印证上表:

• 产物命名规则为 opencode-desktop-${os}-${arch}.${ext}(electron-builder.config.ts#L45),与 README 文件名完全对应;
• macOS 目标为 dmg + zip,开启 hardenedRuntime 与 notarize(electron-builder.config.ts#L75-L84);
• Windows 目标为 NSIS 一键安装器(oneClick: true,对应 .exe);
• Linux 目标同时产出 AppImage、deb、rpm(electron-builder.config.ts#L106-L118);
• 通过环境变量 OPENCODE_CHANNEL 区分 dev / beta / prod 三条发布通道,对应不同的应用 ID(ai.opencode.desktop.dev / .beta / 正式版)与发布仓库,dev 通道还会把 CLI 二进制一并打进 extraResources(electron-builder.config.ts#L32-L42)。

内置 Agents:build、plan 与 general

OpenCode 内置两个主 Agent,在终端中以 Tab 键切换:

• build - 默认开发 Agent,拥有完整权限,按配置的权限规则执行各类工具;
• plan - 只读分析 Agent,用于代码探索与方案规划:
  • 默认拒绝文件编辑;
  • 执行 bash 命令前会先询问;
  • 适合探索陌生代码库或规划变更;

此外还有一个 general 子 Agent,面向复杂检索与多步骤任务,内部调度使用,也可以在消息中用 @general 显式调用。

源码中的权限模型

上述行为在 packages/opencode/src/agent/agent.ts 中有完整定义。所有 Agent 共享一套基于 Effect Schema 的 Info 结构(名称、描述、mode(subagent/primary/all)、native、hidden、温度、权限规则集、模型覆写等,agent.ts#L35-L55),而每个内置 Agent 的差异化全部体现在 Permission.merge 合并的权限规则上:

• build(agent.ts#L140-L155):在默认规则(通配允许、.env 读取需询问等)之上,将 question 设为 allow、plan_enter 设为 allow,即 build 模式下可以进入计划模式,且可以回答用户提问;
• plan(agent.ts#L156-L181):
  • edit 规则为 "*": "deny",仅放行两处写入:项目内 .opencode/plans/*.md 与全局数据目录下的 plans 目录——这解释了"plan 模式只读,但仍可产出计划文档"的行为;
  • task.general 设为 deny(计划期间不允许再派发 general 子任务),plan_exit 设为 allow(允许退出计划模式);
  • 外部目录默认 ask,只有计划目录白名单为 allow;
• general(agent.ts#L182-L195):mode: "subagent",只额外禁用 todowrite,其余继承默认规则,因此可作为后台研究/执行单元被主 Agent 并行调用;

从源码结构看,仓库中还定义了 explore 子 Agent(专用于快速检索代码库,放行 grep/glob/list/bash/webfetch/websearch/read 等只读工具,agent.ts#L196-L218),以及 compaction、title、summary 三个 hidden: true 的内部 Agent(分别负责会话压缩、标题与摘要生成,agent.ts#L219-L264)。这些不在 README 的对外列表中,属于内部机制。

默认 Agent 与自定义覆写

同一文件还揭示了默认 Agent 的选取与自定义机制:

• defaultInfo() 优先读取配置项 default_agent,但要求该 Agent 存在、非 subagent、非 hidden,否则抛错;未配置时回退到第一个可见的 primary Agent(即 build)(agent.ts#L328-L340);
• list() 会把默认 Agent 排在最前,其余按名称排序,这正是 TUI 中 Agent 列表的展示顺序(agent.ts#L316-L326);
• 配置文件中的 agent 段可以覆写任意内置 Agent(模型、温度、提示词、权限等),设置 disable: true 可整体移除某内置 Agent;未定义的新名称则以 mode: "all" 创建为用户 Agent(agent.ts#L267-L294)。

因此,若希望默认进入 plan 模式、或给 build 收紧 bash 权限,均可通过配置文件完成,而不需要修改源码。

参与贡献与命名规范

• 贡献:提交 Pull Request 前请先阅读 CONTRIBUTING.md,其中说明了对应的开发流程要求;
• 基于 OpenCode 构建:如果你在做的项目名称包含 "opencode"(如 opencode-dashboard、opencode-mobile),README 要求在该项目 README 中明确声明:它不是由 OpenCode 团队构建的,与 OpenCode 项目没有任何关联。

小结

• 安装首选 curl -fsSL https://opencode.ai/install | bash,安装脚本自动处理平台/架构/musl/AVX2 基线探测、指定版本安装与 PATH 写入,可用 --version / --binary / --no-modify-path 精确控制;
• 桌面应用(BETA)按平台提供 dmg / exe / deb / rpm / AppImage,产物命名与 electron-builder 配置一一对应,并有 dev / beta / prod 三条发布通道;
• 两个主 Agent(build / plan)以 Tab 切换,权限差异全部来自 agent.ts 中的权限规则合并;general 子 Agent 负责多步骤研究,可用 @general 显式触发;
• 深入配置(模型、Agent 覆写、权限)请查阅官方 Docs,仓库内文档源见 packages/docs。