OpenCode 安装与配置指南：安装脚本、桌面应用与内置 Agent 机制

2026-09-06 15:10:45作者：乔或婵

OpenCode 是一个开源 AI 编码代理（coding agent），支持终端 TUI、桌面应用与 Web 多种形态。本文以仓库根目录的官方 README（含韩语版等多语言版本）为主体，覆盖完整安装方式、安装目录优先级、桌面应用分发与内置 Agent 权限模型，并结合仓库内的安装脚本与 Agent 源码实现，说明每个环节背后的实际行为，帮助你在任意操作系统上正确完成部署并理解 build / plan / general 三类代理的边界。

一、安装

1.1 快速安装（curl 脚本）

官方推荐的一条命令安装方式：

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

提示（官方建议）：安装新版之前，请先移除 0.1.x 之前的旧版本，避免二进制冲突。

1.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（官方 tap，推荐，更新最及时）
brew install opencode              # macOS 及 Linux（Homebrew 官方 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 分支

其中 Nix 支持两条路径：nix run nixpkgs#opencode 走 nixpkgs 稳定版，github:anomalyco/opencode 则直接构建最新 dev 分支——仓库根目录下的 flake.nix 与 flake.lock 即对应的 Nix 定义。

1.3 安装脚本的实现细节（源码级）

仓库根目录的 install 脚本就是随仓库分发的安装器。对照源码，可以确认它比 README 描述的更多几项能力，均可在 install#L10-L27 的帮助文本中查证：

选项	作用
`-v, --version <ver>`	安装指定版本（如 `1.0.180`），下载前会先校验该 Release 是否存在（404 则报错退出）
`-b, --binary <path>`	跳过下载与平台探测，直接从本地二进制文件安装
`--no-modify-path`	不修改任何 shell 配置文件（`.zshrc`、`.bashrc` 等）

脚本的下载与安装流程（install#L79-L204）包含以下可验证的行为：

平台探测：仅支持 linux-x64 / linux-arm64 / darwin-x64 / darwin-arm64 / windows-x64 五种组合，其余直接报错退出；macOS Intel 上通过 sysctl.proc_translated 检测 Rosetta 转译，若处于转译环境会自动改选 arm64 构建；
Linux 特化检测：通过 /etc/alpine-release 或 ldd --version 识别 musl libc，自动追加 -musl 后缀；Linux 包为 .tar.gz（依赖 tar），其余平台为 .zip（依赖 unzip）；
CPU 基线回退：x64 平台上检测 AVX2 指令集（Linux 读 /proc/cpuinfo、macOS 读 hw.optional.avx2_0、Windows 通过 PowerShell 调 IsProcessorFeaturePresent），不支持 AVX2 时自动下载 -baseline 版本二进制；
版本查询：未指定版本时从 GitHub Releases API 获取最新 tag 号，并打印已安装版本以判断是否需要升级（install#L221-L235）。

安装完成后，脚本会按当前 shell（fish / zsh / bash / ash / sh）把安装目录写入对应的配置文件并追加 PATH（install#L362-L439）；若运行在 CI 中（GITHUB_ACTIONS=true），则会写入 $GITHUB_PATH 供后续步骤使用。脚本结尾还会打印上手指引：进入项目目录后直接运行 opencode 命令即可。

二、桌面应用（BETA）

除终端形态外，OpenCode 也提供桌面应用，可从 Release 页或官方下载页获取。各平台产物命名如下（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

桌面应用由 packages/desktop 中的 Electron 工程构建，其产物命名规则可在 electron-builder.config.ts#L45 中得到印证：artifactName: "opencode-desktop-${os}-${arch}.${ext}"，与上表文件名一一对应；该包还保留了旧的 opencode-desktop.desktop 桌面入口文件以兼容既有 GNOME/KDE 用户（electron-builder.config.ts#L13-L16）。

2.1 安装目录优先级

安装脚本按以下顺序决定安装路径：

$OPENCODE_INSTALL_DIR —— 自定义安装目录；
$XDG_BIN_DIR —— 符合 XDG Base Directory Specification 的路径；
$HOME/bin —— 标准用户二进制目录（已存在或可创建时）；
$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），且安装后对二进制执行 chmod 755（install#L343-L344），与上表第 4 级兜底行为一致；线上分发的脚本以 README 所述四级优先序为准。

三、内置 Agents

OpenCode 内置 2 个主代理，在终端中按 Tab 键切换：

build —— 默认代理，拥有完整开发执行权限的 agent；
plan —— 只读分析代理，用于分析、探索代码与规划改动：
- 默认拒绝文件编辑；
- 执行 bash 命令前会请求授权；
- 适合探索陌生代码库或规划变更。

此外还有一个 general 子代理，用于复杂检索与多步骤任务。它内部使用，可在消息中以 @general 调用。

3.1 源码中的权限模型

上述代理行为可在 packages/opencode/src/agent/agent.ts#L140-L195 中得到逐条印证：

build（mode: "primary"）：在默认权限基础上把 question 与 plan_enter 设为 allow，即可以向你提问并进入计划模式；默认权限中 read 对 *.env 文件一律降级为 ask（需要授权），避免把密钥类文件内容直接暴露给模型（agent.ts#L119-L136）；
plan（mode: "primary"）：编辑权限整体为 deny，仅放行计划文档写入——.opencode/plans/*.md 及全局数据目录下的 plans/*.md；同时 task.general 被设为 deny，意味着计划模式内不会再派生 general 子代理，符合“只规划、不动手”的定位；
general（mode: "subagent"）：面向复杂问题的通用子代理，额外禁用 todowrite（避免子代理篡改主会话的任务清单），权限其余部分继承默认策略。

从源码结构看，该文件还定义了另一个原生子代理 explore（agent.ts#L196-L218）：只允许 grep、glob、list、read、bash、webfetch、websearch 等只读类工具，专用于快速探索代码库。README 未将其列为用户可直接切换的代理，但它是子代理体系的一部分，理解权限模型时值得留意。

用户可通过配置文件中的 permission 字段进一步覆盖以上默认值——代理最终权限是“默认策略 + 各代理策略 + 用户配置”三者按序合并（Permission.merge，见 agent.ts#L138-L152）。更多代理配置见官方文档（opencode.ai/docs，仓库内 docs 目录即其源码）。

四、贡献与品牌规范

贡献：向 OpenCode 提交 Pull Request 之前，请先阅读 CONTRIBUTING.md。仓库采用 Bun + monorepo 组织（package.json），根脚本 dev 直接运行 packages/opencode 的入口 src/index.ts；注意根目录的 test 脚本会拒绝执行，测试需在各 workspace 包内单独运行。
基于 OpenCode 做衍生项目：如果你的项目名包含 “opencode”（如 “opencode-dashboard”“opencode-mobile”），README 明确要求在该项目 README 中声明其与 OpenCode 团队无关、也未以任何方式与之关联。