OpenCode 安装指南多平台安装方式、桌面应用与 build/plan 双代理机制解析【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencodeOpenCode 是一个开源的 AI 编程代理coding agent本文基于仓库根目录的乌克兰语版 READMEREADME.uk.md与英文主文档 README.md 内容一一对应系统讲解其全部安装途径——curl 脚本、npm、Homebrew、Scoop、Chocolatey、pacman、mise、Nix 等——并深入剖析仓库中随附的安装脚本 install 的底层逻辑架构探测、baseline 回退、安装目录优先级最后结合源码说明 build / plan / general 三个内建代理的权限差异与切换机制。读完本文你可以完成 OpenCode 在任意主流平台上的安装与 PATH 配置并理解其代理权限模型在源码中的实现方式。一、项目定位仓库自述为 “The open source AI coding agent”开源 AI 编程代理。OpenCode 以终端 TUITerminal User Interface为主要交互形态安装后即可在任意项目目录中通过opencode命令启动。安装脚本结束时会给出两步上手提示见 install 脚本末尾输出cd project # 进入你的项目目录 opencode # 运行命令启动需要注意的是官方提示在安装新版本前应先删除 0.1.x 以下的旧版本避免二进制冲突。二、安装方式总览README 提供了两大类安装途径一键脚本与包管理器。完整命令如下继承自 README.md 的 Installation 章节# YOLO curl -fsSL https://opencode.ai/install | bash # 包管理器 npm i -g opencode-ailatest # 或 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 LinuxStable paru -S opencode-bin # Arch LinuxAUR 最新版 mise use -g opencode # 任意操作系统 nix run nixpkgs#opencode # 或 github:anomalyco/opencode 获取最新 dev 分支各途径的适用场景可以概括为途径平台特点curl \| bash脚本macOS / Linux / Windows无需 root安装到用户目录自动探测架构npm / bun / pnpm / yarn全平台适合已有 Node 工具链的环境包名为opencode-aiHomebrew tapanomalyco/tapmacOS / Linux官方推荐更新最及时Homebrew 官方公式macOS / Linux公式库收录更新节奏较慢Scoop / ChocolateyWindows两种 Windows 主流包管理器均有官方包pacman / AURArch Linuxopencode稳定版与opencode-binAUR 最新版mise任意操作系统通过版本管理器全局安装Nix任意支持 Nix 的系统nixpkgs#opencode或指定 GitHub 仓库取 dev 分支三、安装脚本深入解析仓库根目录的 install 脚本正是curl -fsSL https://opencode.ai/install | bash下载并执行的实体通读其源码可以弄清脚本的完整行为边界而不只是照抄命令。3.1 支持的命令行选项脚本参数解析部分install 第 10–27 行的usage说明定义了三个选项-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其中--version会先通过 GitHub API 校验该 tag 是否存在404 时直接报错退出--binary则会跳过全部下载与架构探测逻辑直接把本地文件复制并chmod 755到安装目录。3.2 平台与架构探测逻辑脚本只接受五种目标组合linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64其余组合直接报错退出。在基础探测之上还有三个值得注意的细节Rosetta 识别Darwin x64通过sysctl.proc_translated判断当前是否运行在 Rosetta 翻译环境下若是则把架构改写为arm64从而为 Apple Silicon 下载原生二进制而不是 x64 版本。musl 检测Linux通过/etc/alpine-release或ldd --version输出识别 musl libc如 Alpine在目标名后追加-musl后缀保证静态链接兼容。AVX2 能力探测baseline 回退x64 平台上会检测 CPU 是否支持 AVX2——Linux 读/proc/cpuinfomacOS 读sysctl hw.optional.avx2_0Windows 则调用kernel32!IsProcessorFeaturePresent(40)通过 powershell/pwsh 执行。不支持 AVX2 的机器会在目标名后追加-baseline下载不带 AVX2 指令的构建产物。这说明官方预编译产物按 CPU 特性分档发布老服务器不会因指令集不兼容而崩溃。产物格式方面Linux 使用.tar.gz要求系统有tar其他平台使用.zip要求unzip缺少对应工具时脚本会提前报错退出。3.3 版本幂等性检查check_version函数会先which opencode若已安装则执行opencode --version比对目标版本版本一致时直接打印 “already installed” 并退出版本不一致时才继续下载安装。这意味着重复执行安装脚本是安全且幂等的。3.4 PATH 配置策略默认安装目录为$HOME/.opencode/bin即 README 中所述的“Default fallback”。安装后脚本按当前 shellfish / zsh / bash / ash / sh选择对应的 rc 文件将安装目录写入 PATHzsh 依次检查~/.zshrc、~/.zshenv及 XDG 路径下的同名文件bash 依次检查~/.bashrc、~/.bash_profile、~/.profile及 XDG 路径fish 使用fish_add_path语句其余 shell 写入export PATH...写入前会先grep判重已存在则跳过文件不可写时打印手动添加的提示而不是硬写若检测到GITHUB_ACTIONStrue还会把安装目录追加进$GITHUB_PATH方便在 CI 中直接调用。配合--no-modify-path选项可以在完全不动 shell 配置的前提下完成安装适合容器或受限环境。四、安装目录优先级README 中“Installation Directory / Каталог встановлення”一节给出了安装脚本对安装路径的四级优先级结合 install 脚本源码可完整还原其语义$OPENCODE_INSTALL_DIR— 自定义安装目录最高优先级$XDG_BIN_DIR— 兼容 XDG Base Directory 规范的路径$HOME/bin— 标准用户二进制目录若已存在或可创建$HOME/.opencode/bin— 默认回退路径脚本中INSTALL_DIR的初始值。README 给出的两个自定义示例# 安装到系统目录通常需要相应权限 OPENCODE_INSTALL_DIR/usr/local/bin curl -fsSL https://opencode.ai/install | bash # 指定 XDG 二进制目录 XDG_BIN_DIR$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash五、桌面应用BETAOpenCode 同时提供桌面客户端目前处于 BETA 阶段可从官方发布页直接下载各平台安装包平台下载产物macOS (Apple Silicon)opencode-desktop-mac-arm64.dmgmacOS (Intel)opencode-desktop-mac-x64.dmgWindowsopencode-desktop-windows-x64.exeLinux.deb、.rpm或 AppImage桌面端同样可以通过包管理器安装# macOS (Homebrew) brew install --cask opencode-desktop # Windows (Scoop) scoop bucket add extras; scoop install extras/opencode-desktop仓库中的packages/desktop/目录即为桌面端的工程实现包含electron-builder.config.ts、主进程src/main/与预加载脚本src/preload/等桌面端的图标资源按beta、dev、prod三套发布渠道分别维护与 BETA 阶段的发布策略相吻合。六、内建代理build / plan / generalREADME 的 “Agents” 章节说明 OpenCode 提供两个可用Tab键切换的内建主代理另有一个辅助子代理build— 默认代理拥有完整权限面向开发任务plan— 只读分析代理默认拒绝文件编辑、执行 bash 命令前请求授权适合探索不熟悉的代码库或规划改动general— 用于复杂搜索与多步骤任务的子代理系统内部使用也可在消息中通过general显式调用。6.1 源码中的代理定义三个代理的具体实现集中在 agent.ts。从源码结构看每个代理由modeprimary/subagent/all、permission权限规则集和可选的prompt、model、temperature等字段构成权限通过Permission.merge按 “默认规则 → 代理专属规则 → 用户配置” 的顺序逐层合并buildagent.tsmode: primary在默认权限基础上放开question与plan_enter即默认权限集读取.env*文件会询问、doom_loop询问等之上获得完整的执行能力。planagent.ts核心约束是edit: { *: deny }——全局拒绝编辑仅放行.opencode/plans/*.md与全局数据目录下的plans/*.md这解释了“只读”并非完全无法写盘而是只允许把规划落盘为 Markdown 计划文件同时task: { general: deny }表明 plan 模式下不会派生 general 子任务。generalagent.tsmode: subagent描述为“用于研究复杂问题、执行多步骤任务可并行执行多个工作单元”仅额外禁用了todowrite工具其余继承默认权限。此外源码中还定义了若干 README 未展开的代理可以补充理解 OpenCode 的代理体系exploreagent.ts专门的代码库探索子代理权限为“默认拒绝 白名单”仅允许grep、glob、list、bash、webfetch、websearch、read等只读类工具且外部目录访问保持只读。compaction / title / summaryhidden: true的系统代理分别用于上下文压缩、会话标题生成与会话摘要全部工具默认拒绝说明这些是纯 LLM 推理任务而非工具型代理。6.2 用户自定义代理的合并机制agent.ts 展示了配置覆盖逻辑用户可通过配置中的agent段按名称扩展或覆盖任意代理包括内建代理支持model、prompt、description、temperature、top_p、mode、color、hidden、steps、options、permission等字段设置disable: true可以直接移除某个内建代理。用户的权限规则永远在合并链的最后一层生效因此可以对内建代理做精细化收权。6.3 TUI 中的代理切换README 提到的Tab键切换对应 TUI 中的agent.cycle/agent.cycle.reverse命令app.tsx二者通过local.agent.move(±1)在代理列表中前进/后退一位主屏幕提示视图也内置了 “press … to cycle between Build and Plan agents” 的引导文案tips-view.tsx。代理列表的排序规则则遵循“默认代理或 build优先、其余按名称升序”见 agent.ts保证 Tab 循环时默认代理始终排在前位。七、延伸阅读与贡献完整的配置说明模型、权限、代理、主题等以官方文档站为准README 在 Documentation 一节将其作为配置问题的唯一权威入口。参与贡献前请先阅读 CONTRIBUTING.md其中约定了 pull request 前的阅读要求。命名约定如果你的项目名中包含 “opencode”如 “opencode-dashboard”、“opencode-mobile”README 要求在其 README 中明确声明该项目并非 OpenCode 团队开发、与官方无任何隶属关系避免社区混淆。多语言 README仓库根目录维护了包括英文README.md、简体中文README.zh.md、乌克兰文README.uk.md在内的二十余个语言版本内容骨架一致。八、小结要点说明推荐安装Linux/macOS 首选brew install anomalyco/tap/opencodeWindows 用 Scoop/Chocolatey无包管理器环境用 curl 脚本固定版本curl … \| bash -s -- --version ver脚本会校验 tag 存在性安装位置默认~/.opencode/bin可用OPENCODE_INSTALL_DIR/XDG_BIN_DIR覆盖产物分档按 OS-架构 组合发布另有-baseline无 AVX2与-muslAlpine变体代理模型build全权限/ plan只读仅可写 plans Markdown/ general子代理general调用Tab 循环切换扩展性通过配置agent段覆盖任意内建代理的模型、提示词与权限以上内容均可在仓库中逐一核验安装行为见 install代理定义与权限合并见 packages/opencode/src/agent/agent.tsTUI 切换命令见 packages/tui/src/app.tsx文档骨架见 README.md 与 README.uk.md。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考