OpenCode 从安装到 Agent 切换开源编码代理的完整上手指南【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencodeOpenCode 是一个开源的 AI 编码代理coding agent以终端 TUI 为核心交互形态同时提供桌面应用形态。本文基于仓库根目录的 README.pl.md波兰语版项目 README其内容与 README.md 各语言版本保持一致展开覆盖全部安装渠道、安装目录优先级规则、BETA 桌面应用的下载方式以及内置 build/plan 双 Agent 的工作机制——读完你可以独立完成 OpenCode 的安装、配置 PATH、切换 Agent 模式并理解安装脚本与 Agent 权限背后的源码实现。什么是 OpenCodeREADME 对项目的定位一句话概括为“Otwartoźródłowy agent kodujący AI”开源 AI 编码代理。从仓库结构看它由多个 workspace 包组成核心运行时位于 packages/opencode终端 UI 位于 packages/tui桌面应用位于 packages/desktop另有 Web 前端 packages/app、文档站 packages/web、控制台 packages/console 等。根目录 package.json 显示项目使用 Bun 作为包管理器packageManager: bun1.3.14以 workspace turbo 的方式组织多包工程。安装完成后OpenCode 提供免费的内置模型即可直接开始使用。安装脚本结尾会打印启动提示cd project # 打开目标项目目录 opencode # 运行命令安装一键安装脚本YOLO 模式curl -fsSL https://opencode.ai/install | bash[!TIP] 安装前请先卸载 0.1.x 之前的旧版本避免版本冲突。这一行命令背后是一个功能完整的 Bash 安装脚本即仓库根目录的 install 文件。结合源码可以了解到它的完整能力命令行参数来自 install 脚本 的usage()函数参数作用-v, --version version安装指定版本例如1.0.180会先校验该 release tag 是否存在404 则报错退出-b, --binary path从本地二进制文件安装跳过所有下载与平台检测逻辑--no-modify-path不修改 shell 配置文件.zshrc、.bashrc等-h, --help显示帮助信息例如安装指定版本curl -fsSL https://opencode.ai/install | bash -s -- --version 1.0.180平台检测与产物选择。脚本通过uname -s/uname -m检测系统支持的平台组合为linux-x64、linux-arm64darwin-x64、darwin-arm64windows-x64含 MINGW / MSYS / CYGWIN 环境并在两个维度上自动降级适配Rosetta 检测在 Apple Silicon 上通过sysctl sysctl.proc_translated识别 x64 转译环境若检测到 Rosetta 则自动改为下载 arm64 产物CPU 指令集降级x64 平台上通过/proc/cpuinfoLinux、sysctl hw.optional.avx2_0macOS或 PowerShell 的IsProcessorFeaturePresentWindows检测 AVX2 支持不支持时自动追加-baseline后缀下载基础指令集版本musl 检测Linux 上通过/etc/alpine-release或ldd --version识别 musl 环境如 Alpine追加-musl后缀。下载与安装流程。脚本会先查询 GitHub Releases API 获取最新 tag拼接opencode-target.zipmacOS/Windows或.tar.gzLinux产物名下载下载前会执行版本幂等性检查check_version——若本机已安装的目标版本与目标一致则直接退出。下载完成后解包、将二进制移动到安装目录并chmod 755。Linux 系统要求tar其他平台要求unzip缺失时会给出明确报错。PATH 自动配置。除非传入--no-modify-path脚本会根据$SHELL选择对应 rc 文件并写入 PATH 导出语句fish~/.config/fish/config.fish写入fish_add_pathzsh~/.zshrc、~/.zshenv含ZDOTDIR与 XDG 路径bash~/.bashrc、~/.bash_profile、~/.profile含 XDG 路径ash / sh~/.ashrc、~/.profile、/etc/profile写入前会先用grep -Fxq检查是否已存在相同语句避免重复追加若文件不可写则打印手动配置提示。在 CI 环境中GITHUB_ACTIONStrue则改为将安装目录追加到$GITHUB_PATH适配 GitHub Actions 的使用场景。包管理器安装各平台也可通过包管理器安装完整清单如下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 与 LinuxHomebrew 官方 formula更新频率较低 sudo pacman -S opencode # Arch LinuxStable 仓库 paru -S opencode-bin # Arch LinuxAUR 最新构建 mise use -g opencode # 任意系统 nix run nixpkgs#opencode # 或使用 github:anomalyco/opencode 获取 dev 分支最新两种 Homebrew 渠道的区别值得注意anomalyco/tap/opencode是团队维护的 tap更新最及时官方 formulaopencode更新频率较低。Nix 用户可以直接nix run nixpkgs#opencode或使用 flake 引用仓库自身仓库根目录提供了 flake.nix 与 flake.lockNix 打包细节见 nix/opencode.nix。桌面应用BETAOpenCode 同时提供桌面应用Beta 阶段可从项目的 Release 页面或官网下载页获取。各平台安装包命名如下平台安装包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从仓库源码结构看桌面应用基于 Electron 生态构建packages/desktop 包含主进程src/main/、preload 与 renderer 三个部分构建配置见 electron-builder.config.ts 与 electron.vite.config.ts打包前脚本图标拷贝、bundle 拷贝、latest.yml收尾等位于 packages/desktop/scripts。安装目录优先级一键安装脚本按以下优先级决定安装路径$OPENCODE_INSTALL_DIR—— 自定义安装目录$XDG_BIN_DIR—— 符合 XDG Base Directory 规范的路径$HOME/bin—— 用户标准 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第 68 行即上述优先级中的最终回退项OPENCODE_INSTALL_DIR与XDG_BIN_DIR的行为以 README 文档描述为准实际生效逻辑可能由发布到安装端点的脚本版本承载。如果你自行分发或复用该脚本回退路径$HOME/.opencode/bin是确定可靠的。内置 Agent 体系build、plan 与 generalOpenCode 内置两个可切换的主 Agent在 TUI 中按Tab键切换build—— 默认 Agent具备完整的开发工作权限plan—— 只读分析 Agent用于代码库探索与改动规划默认拒绝编辑文件执行 bash 命令前会请求授权适合熟悉陌生代码库或规划改动方案此外还有一个内部general子 Agent用于复杂检索与多步骤任务可在消息中通过general显式调用。这一 Agent 体系在源码中有直接对应packages/opencode/src/agent/agent.ts 中定义了build、plan、general等内置 Agent 及其modeprimary/subagent。从源码结构看plan 模式的权限控制是显式声明的edit工具默认deny仅放行.opencode/plans/*.md以及全局数据目录下plans/*.md的计划文件写入——这解释了“plan 模式默认拒绝编辑文件”的设计它并非完全不能写而是只能把规划结果写入约定的计划文件build模式则额外放开了question提问与plan_enter进入 plan 模式权限general以subagent模式注册描述为“用于研究复杂问题并执行多步任务”并禁用了todowrite工具。除这两个主 Agent 外源码中还注册了explore快速代码库探索只开放 grep/glob/list/bash/read/webfetch/websearch 等只读类工具与隐藏的compaction、title等辅助 Agent说明 Agent 权限模型Permission.fromConfig/Permission.merge的默认值 覆盖 用户配置三层合并是整个工具权限体系的统一基础用户配置中的permission字段会作为最高优先级覆盖进去。文档、贡献与命名规范配置与进阶用法README 指向官方文档站docs.opencode 的文档入口在仓库 README.md 中给出仓库内 packages/docs 提供了配套的文档源含 OpenAPI 定义 openapi.json 与 SDK 文档 packages/sdk。贡献流程参与开发前请阅读 CONTRIBUTING.md在提交 Pull Request 之前遵循其中约定。仓库根目录的 AGENTS.md 也面向 AI 协作贡献者给出了工程约定。构建在 OpenCode 之上的项目如果你的项目名包含 “opencode”例如 “opencode-dashboard”、“opencode-mobile”README 要求在 README 中明确注明该项目并非 OpenCode 团队制作、与其无任何关联——这是避免品牌混淆的社区约定。小结主题关键点一键安装curl -fsSL https://opencode.ai/install \| bash支持指定版本、本地二进制、不修改 PATH安装目录OPENCODE_INSTALL_DIRXDG_BIN_DIR$HOME/bin$HOME/.opencode/bin包管理器npm / bun / pnpm / yarn、Scoop、Chocolatey、Homebrewtap 与 formula 两种渠道、pacman、paru、mise、Nix桌面应用BETA 阶段支持 macOS / Windows / Linuxbrew install --cask opencode-desktopAgentTab切换 build 与 plangeneral调用子 Agent权限由 agent.ts 中的声明式 Permission 配置驱动前置清理安装前移除 0.1.x 之前的旧版本【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考