OpenCode 开源 AI 编程代理：多平台安装、桌面应用与 Agent 模式实战指南

2026-09-06 11:41:49作者：裴麒琰

OpenCode 是一个开源的 AI 编程代理（coding agent），可在终端中以 TUI 形态与代码库交互。本篇基于仓库内的 README 及其意大利语版本 README.it.md 的完整内容展开，覆盖全部安装渠道、桌面应用分发方式、安装目录规则，并结合仓库源码（安装脚本、Agent 定义）深入讲解 build / plan 双代理的权限模型，读完后可独立完成从安装、版本固定到代理切换的完整落地流程。

安装方式

OpenCode 提供“一键脚本 + 多包管理器”两种安装路径，覆盖 macOS、Linux 与 Windows：

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

# Package manager
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 Latest）
mise use -g opencode               # 任意操作系统
nix run nixpkgs#opencode           # 或 github:anomalyco/opencode 安装最新开发分支

提示：安装前请移除 0.1.x 之前的旧版本，以避免新旧命令冲突。当前仓库中 packages/opencode/package.json 的版本号已是 1.x（1.18.29），说明项目已跨过 0.1.x 阶段，旧版二进制与新配置/目录布局并不兼容。

安装脚本的源码级细节

仓库根目录的 install 脚本即为上文 curl | bash 的参考实现，从源码可以看到它比“下载一个二进制”做的事更多：

参数解析（install#L33-L66）：支持 -v/--version <version> 安装指定版本（会先调用 release 接口验证 tag 存在，404 即报错退出）、-b/--binary <path> 从本地二进制文件离线安装（跳过全部下载与平台探测逻辑）、--no-modify-path 不修改任何 shell 配置文件。
平台探测（install#L79-L110）：通过 uname 识别 darwin/linux/windows 与 x64/arm64 组合，仅接受 linux-x64|linux-arm64|darwin-x64|darwin-arm64|windows-x64 五种组合；在 macOS x64 上还会检测 Rosetta 翻译标志，若处于 Rosetta 下则改用 arm64 产物。
CPU 与 libc 适配（install#L117-L166）：Linux 下通过 /etc/alpine-release 或 ldd --version 识别 musl libc，追加 -musl 后缀；对 x64 目标额外检测 AVX2 支持（Linux 查 /proc/cpuinfo、macOS 查 hw.optional.avx2_0、Windows 通过 PowerShell 调 IsProcessorFeaturePresent），不支持 AVX2 时回退到 -baseline 构建，保证在老 CPU 上也能运行。
版本幂等检查（install#L221-L235）：若 opencode 已存在于 PATH 且版本与目标版本一致，直接退出，避免重复下载。
PATH 配置（install#L380-L444）：根据 $SHELL 自动选择 ~/.zshrc、~/.bashrc、~/.config/fish/config.fish 等配置文件追加 PATH 导出语句，已存在则跳过；在 GitHub Actions 环境下还会把安装目录写入 $GITHUB_PATH，方便 CI 中直接使用。

固定版本的用法示例：

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

安装目录

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

$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 脚本将 INSTALL_DIR 硬编码为 $HOME/.opencode/bin，并未在本地脚本中实现上述 OPENCODE_INSTALL_DIR / XDG_BIN_DIR 的前缀检测。从源码结构看，README 描述的优先级规则对应的是线上 opencode.ai/install 分发的安装器，与仓库内的参考实现可能存在差异，实际行为以线上脚本为准。

桌面应用（BETA）

OpenCode 同时提供桌面应用形态，可从发布页或下载页获取。各平台安装包命名如下：

平台	安装包
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 应用，内部封装了共享的 Web UI 组件包 packages/app（见 CONTRIBUTING.md 的“Core pieces”一节）。若需要本地构建桌面端，可按贡献指南执行：

bun run --cwd packages/desktop dev       # 开发模式
bun run --cwd packages/desktop build    # 生产构建
bun run --cwd packages/desktop package  # 打包

Agent 模式：build 与 plan

OpenCode 内置两个可用 Tab 键切换的一级代理（primary agent）：

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

另外还内置 general 子代理（subagent），面向复杂检索与多步骤任务，可在消息中通过 @general 显式调用。

源码中的权限模型

以上行为并非仅靠文档约束，而是由 packages/opencode/src/agent/agent.ts 中的权限规则集（permission ruleset）硬性实现的。每个代理定义都会把默认规则、代理专属规则与用户配置（cfg.permission）三层合并：

build（agent.ts#L141-L155）：在默认规则之上放开 question 与 plan_enter，允许用户从 build 切回 plan；默认规则中 *.env、*.env.* 等敏感文件读取为 ask（agent.ts#L130-L135），即读取环境文件前需确认，.env.example 除外。
plan（agent.ts#L156-L181）：edit 规则为 * = deny，仅放行 .opencode/plans/*.md 与全局数据目录下 plans/ 中的 Markdown 文件——也就是说 plan 代理“只读代码、只写计划文档”，其写入面被严格限定在计划文件上；同时禁止派发 general 子任务（task: { general: "deny" }），保证探索过程串行、可控。
general（agent.ts#L182-L195）：mode: "subagent"，描述为面向复杂问题研究与多步并行任务的通用代理，禁用 todowrite 工具，避免子代理篡改主会话的任务清单。
源码中还包括两个隐藏（hidden: true）的内部代理 compaction（上下文压缩）与 title（会话标题生成，temperature 0.5），以及只读探索特化的 explore 子代理（仅允许 grep/glob/list/bash/webfetch/websearch/read 等工具，见 agent.ts#L196-L218）——这些是支撑 plan/build 体验的底层机制。

默认代理的选择逻辑也在同一文件中：若用户在配置中指定了 default_agent 则遵循之，否则回退到 build（agent.ts#L322 附近的排序逻辑）。

文档与二次开发

更完整的配置说明（代理自定义、权限、模型配置等）以官方文档站为准；仓库内 packages/docs/ 目录维护着对应的文档源（packages/docs/README.md），包括 AI 工具集成指南（ai-tools/ 下含 Claude Code、Cursor、Windsurf 的说明）与功能配置文档。

贡献与本地构建

有意贡献 OpenCode 时，请先阅读 CONTRIBUTING.md：所有 PR 必须关联已有 issue（Issue First Policy）、PR 标题遵循 conventional commit 规范（feat: / fix: / docs: 等，可带包名 scope 如 fix(desktop):）、UI 改动需附前后对比截图。本地开发流程为：

bun install
bun dev <directory>   # 在指定目录启动 TUI；bun dev . 作用于仓库根目录
bun dev serve         # 启动 headless API 服务器（默认 4096 端口，--port 可指定）
bun dev web           # 启动服务器并打开 Web 界面

构建独立可执行文件（localcode）：

./packages/opencode/script/build.ts --single
./packages/opencode/dist/opencode-<platform>/bin/opencode   # <platform> 如 darwin-arm64、linux-x64

基于 OpenCode 构建衍生项目

如果你的项目与 OpenCode 相关且名称中包含 “opencode”（例如 “opencode-dashboard” 或 “opencode-mobile”），请在你的 README 中注明：该项目并非由 OpenCode 团队开发，与官方无任何隶属关系。这是官方 README（含 README.it.md 等全部语言版本）中明确提出的品牌规范，目的是避免社区对官方背书产生误解。

小结

本文继承并扩充了 OpenCode 官方 README（意大利语版 README.it.md）的四大板块：多包管理器安装、桌面应用（BETA）、双代理模式与贡献规范。要点回顾：

安装优先选 Homebrew 官方 tap 或一键脚本；脚本支持 --version 固定版本与 --binary 离线安装，并自动处理 musl/AVX2/Rosetta 等平台差异（install）；
桌面端各平台安装包命名与 Homebrew cask / Scoop 渠道已在源码层面由 packages/desktop 支撑；
build/plan 的行为差异由权限规则集在 agent.ts 中硬编码实现，plan 代理的写权限被限定到 plans/ 下的 Markdown 文件，这是其“只读”语义的准确边界；
二次开发遵循 CONTRIBUTING.md 的 Issue First 与 PR 规范，bun dev 与产物 opencode 命令行为等价。