本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文

安装与运行时渠道

状态：生效 范围：当前状态 最近审阅：2026-10-09 负责人：ax-code 运行时

根目录的 README 保留主要安装路径。本页是受支持 CLI 安装器渠道、ax-code doctor 运行时标签、本地启动器行为，以及公开升级行为的权威来源。

公开可用性

公开版本安装器和已签名的运行时归档通过 download.ax-code.com 分发。安装不需要私有的 GitHub 凭据。

AX Code 和 SDK 只支持 Node.js 26 或更高版本。独立安装器捆绑 经过验证的 Node 运行时。源码检出和基于 Node 的 SDK 应用必须自行提供 Node.js 26+；包安装会拒绝更旧的 Node 版本。

AX Code Standard 在其现有许可证下，个人与商业用途仍然免费。 开发源码访问与公开分发分开管理。规划中的 专有 Business 组件有单独的许可；这不会改变 Standard 的许可证。细节见 Standard 与 Business，公开安装更新见 网站指南。 公开安装器及其已签名资产必须可访问并经过验证，然后 网站才会宣传一行安装命令。

版本可用性

推送 vMAJOR.MINOR.PATCH git 标签会启动 Release 工作流。 公开版本索引 列表只有在 该工作流签名了资产并发布之后才会显示某个 版本。在此之前，Latest 停留在上一个已发布的标签。验证成功之后，维护者可以 看到新标签的 Draft；它不是公开的 Latest。

对于现有安装，请遵循 升级与恢复。

推荐路径

除非你正在从检出进行开发，否则请使用受支持的打包安装器。发行版安装器是 macOS 和 Linux 上的主要 CLI 路径；在 Windows 上使用原生 PowerShell 安装器。

macOS（Apple Silicon）

curl -fsSL https://download.ax-code.com/install | bash

Windows 安装

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://download.ax-code.com/install.ps1 | iex"

Ubuntu 24.04+

curl -fsSL https://download.ax-code.com/install | bash

Homebrew 仍然是 macOS CLI 的受支持替代方案：

brew tap defai-digital/tap
brew trust defai-digital/tap
brew install defai-digital/tap/ax-code

Homebrew 对非官方 tap 要求显式信任。这种整 tap 信任覆盖 defai-digital/tap 中当前和将来发布的全部 formula、 cask 和外部命令。共享 tap 同时包含 CLI formula 和 桌面 cask，Homebrew 在解析安装时可以加载这两份定义。如果 整 tap 信任不可接受，请改用发行版安装器。

把现有安装从遗留 tap 迁出

defai-digital/ax-code 现在只是迁移用的 tap。AX Code 版本只更新 defai-digital/tap。如果你是从遗留 tap 安装的，请在更新之前添加共享 tap， 以便 Homebrew 能够转移已安装包的 tap 所有权：

brew tap defai-digital/tap
brew trust --formula defai-digital/tap/ax-code
brew update
brew upgrade defai-digital/tap/ax-code
brew info defai-digital/tap/ax-code

确认安装使用共享 tap 之后，移除遗留 tap：

brew untap defai-digital/ax-code

如果 Homebrew 仍然报告旧 tap，请在取消 tap 之前运行 brew reinstall defai-digital/tap/ax-code。遗留 仓库对现有安装仍然可访问，以便发现迁移。

验证按版本钉住的 Unix 安装器

对于经过检查、按版本钉住的 Unix 安装，请先从同一次发布下载安装器及其签名。在已经有受信任的 minisign 时：

AX_INSTALL_VERSION="<release>"
AX_INSTALL_BASE="https://download.ax-code.com/releases/download/v${AX_INSTALL_VERSION}"
curl -fsSL "$AX_INSTALL_BASE/install" -o ax-code-install
curl -fsSL "$AX_INSTALL_BASE/install.minisig" -o ax-code-install.minisig
minisign -Vm ax-code-install -x ax-code-install.minisig -P 'RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO'
# Inspect ax-code-install before running it.
bash ax-code-install --version "$AX_INSTALL_VERSION" --no-modify-path

归档的签名并不会在执行之前认证引导脚本。 从同一来源下载的摘要可以发现损坏，但不是独立的 发布者身份检查。一行路径依赖 HTTPS 分发端点。

一行远程执行是便利路径。Windows 安装器在启动后会用 Minisign 验证已下载的 CLI ZIP，但 irm | iex 在执行之前并不会验证 install.ps1 本身。

如果 minisign 尚不在 PATH 上，PowerShell 安装器会从 download.ax-code.com 下载钉住的 minisign 0.12 归档，检查其 SHA-256，并在缓存之前再次检查解压出的可执行文件。默认安装路径不需要你手动安装 minisign。已经在 PATH 上的 minisign 二进制会按原样使用。

对于安全敏感的环境，请下载安装器，用 Minisign 验证，检查它，并钉住 CI 使用的发布版本：

$AX_CODE_VERSION = "<release>"
$AxCodeMinisignPublicKey = "RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO"
irm https://download.ax-code.com/install.ps1 -OutFile ax-code-install.ps1
irm https://download.ax-code.com/install.ps1.minisig -OutFile ax-code-install.ps1.minisig
# Optional: use a preinstalled minisign, or let install.ps1 bootstrap one when verifying the archive.
minisign -Vm ax-code-install.ps1 -x ax-code-install.ps1.minisig -P $AxCodeMinisignPublicKey
Get-Content .\ax-code-install.ps1
.\ax-code-install.ps1 -Version $AX_CODE_VERSION -NoModifyPath

只有当你有意接受无法验证的发布下载时，才设置 AX_CODE_SKIP_MINISIGN_VERIFY=1。

验证已安装的运行时：

ax-code doctor

受支持的用户安装在 macOS、Windows 和 Linux（glibc）上应当报告 Runtime: Node vX.Y.Z (node-bundled)。

这些安装器分发的是 CLI/TUI 运行时。桌面版本的所有权在 AX Coder，并且新的桌面版本目前冻结。本指南不 提供桌面安装或升级渠道。

渠道矩阵

node-bundled 和 source 是运行时模式，不是包管理器名称。它们描述哪个可执行文件加载应用代码：

• node-bundled：Node.js 加载捆绑的发行版运行时（所有受支持的用户安装渠道）。
• source：Node 直接从检出加载文件。

compiled 和 bun-bundled 是已退役的 Bun 时代运行时模式，只为遗留诊断保留。它们不是受支持的用户安装渠道。

pnpm dev 和 pnpm cli 会在启动前用仓库的 TypeScript 把工作区 SDK（packages/sdk/js）编译到 dist，因此全新检出无需手动构建 SDK 就能运行。该步骤直接调用 typescript/bin/tsc，经由 node，因此不依赖 node_modules/.bin 已被链接。捆绑路径（pnpm run setup:cli 和 pnpm --dir packages/ax-code run build）仍然需要先有 pnpm --dir packages/sdk/js run build。

平台策略

• macOS：把 bash 发行版安装器作为主要记录的 CLI 路径。它安装在 ~/.ax-code 下，需要时引导钉住的 Minisign，验证发行归档，并且不需要 Homebrew。darwin-arm64 归档包含用于本地推理的自包含 AX Engine 边车。贡献者构建使用 pnpm run setup:cli。
• 受支持的 Homebrew 路径会在使用完全限定的安装命令之前，显式 tap 并信任 defai-digital/tap。整 tap 信任包括共享 tap 中当前和将来的全部 formula、cask 和外部命令；当该信任范围不可接受时，请使用 bash 发行版安装器。
• Linux CLI：在 amd64 和 arm64（glibc）上，为 Ubuntu Desktop/Server 24.04 LTS 及更新版本使用 bash 安装器。发行构建在 Ubuntu 24.04 运行器上产生 ax-code-linux-x64.tar.gz 和 ax-code-linux-arm64.tar.gz，以便 glibc 基线与 24.04+ 保持兼容。当前发行归档不支持 Musl（Alpine）。
• macOS CLI 归档：发行构建只发布 darwin-arm64（Apple Silicon）。Intel macOS 不是当前 CLI/桌面包的受支持安装目标。
• Windows CLI：使用原生 PowerShell 安装器。它把 GitHub 发行资产安装到用户本地目录，并更新用户 PATH，除非提供了 -NoModifyPath。它会在解压之前用钉住的公钥验证已下载的 ZIP，并且除非有意设置了 AX_CODE_SKIP_MINISIGN_VERIFY=1，否则失败即关闭。如果缺少 minisign，安装器会从 download.ax-code.com 把钉住的 minisign 0.12 归档下载到 %LOCALAPPDATA%\ax-code\tools\minisign，并在缓存之前检查解压出的可执行文件。已经在 PATH 上的 minisign 二进制会按原样使用。使用 -Uninstall 移除用户本地安装和 PATH 条目。
• Windows 桌面：使用来自 GitHub Releases 的已签名 Electron 安装器，名为 AX-Code-<version>-win-x64.exe 或 AX-Code-<version>-win-arm64.exe。预期的 Authenticode 发布者是 DEFAI Private Limited。不要把 install.ps1 描述成桌面安装器。静默安装：.\AX-Code-<version>-win-x64.exe /S（NSIS）。
• Winget：包清单用 pnpm exec tsx tools/winget/generate-manifests.ts --version <ver> 生成，并提交到 microsoft/winget-pkgs（见 tools/winget/README.md）。在上游发布之前，GitHub Releases 仍然是 Windows 安装的权威来源。
• npm：不是受支持的安装或升级渠道。

一行远程执行是便利路径，不是唯一路径。在文档中保留可检查的（在 Windows 上还要用 Minisign 验证的）安装器流程，在 CI 中使用钉住的版本，并且只有在安装矩阵覆盖能够验证 ax-code --version、并验证 ax-code doctor 报告该平台预期的运行时模式时，才记录平台安装器。

企业与无人值守安装

Windows CLI（用户本地，无需管理员）

# Pin version in CI/images
$env:AX_CODE_VERSION = "7.9.4"
irm https://download.ax-code.com/releases/download/v$env:AX_CODE_VERSION/install.ps1 -OutFile install.ps1
# Optional: verify install.ps1.minisig first (see SECURITY.md)
.\install.ps1 -Version $env:AX_CODE_VERSION -NoModifyPath
# Then add %USERPROFILE%\.ax-code\bin to the machine/user PATH via your MDM.

macOS（用户本地 / Homebrew / MDM）

不使用 Homebrew 的用户本地 CLI 安装，请使用发行版安装器：

curl -fsSL https://download.ax-code.com/install | bash

受管理的 Mac 可以使用 Homebrew formula，以便 CLI 更新跟随 tap：

brew tap defai-digital/tap
brew trust defai-digital/tap
brew install defai-digital/tap/ax-code

对于 MDM 打包的 DMG 安装，使用来自 GitHub Releases 的已公证 AX-Code-*-mac-arm64.dmg，并在策略要求供应链检查时验证分离的 .minisig。

Winget 可用性

除非已有经过验证的社区 CLI 包，否则使用公开安装器。 不要假定 GitHub 托管的清单包可以匿名访问。

更新

选择拥有当前安装的渠道：

现有的遗留 tap 用户应遵循 共享 tap 迁移。第二次安装可能在 PATH 上遮蔽 第一次；在 更换渠道之前使用 which -a ax-code、ax-code --version 和 ax-code doctor。安装独立版本并不会卸载 Homebrew。 只在有意时才在渠道之间移动，并保留你的会话/配置数据。

Unix 自升级会从目标版本获取安装器，并要求其 SHA-256 边车。缺少安装器或摘要会停止升级；没有可变 main 回退。要从一次没有安装器资产的发布安装较旧的归档，请下载 并验证当前已发布的安装器，然后用 --version <older-version> 运行它。

独立 Unix 安装使用 ~/.ax-code/bin/ax-code 作为指向 ~/.ax-code/versions/ 下唯一 运行时代的稳定符号链接。安装器会在切换该链接之前验证完整的 新树。重新安装某个版本会创建新的一代。 它保留旧的代和遗留运行时文件，以便已经在运行的代理可以 继续加载自己的模块。它不会重启正在运行的代理。启动新的 客户端/运行时才能使用新版本；在运行时 重启之前，请显式停止活动工作。Homebrew 文件仍然由 Homebrew 管理。

回滚时，使用带 --version <previous-version> 的已验证安装器。每一代保留的 version 文件标识其发布。旧的代不会被自动 修剪；在停止所有使用它们的进程之后，你可以移除未使用的代。 卸载期间，如有需要，用 --keep-data --keep-config 保留会话/配置； 遵循二进制移除指引，并且只在 其进程停止之后，才单独移除未使用的运行时代。如果你在 .ax-code 文件夹中存放了 其他配置或个人文件，不要删除整个文件夹。

并发的 Unix 安装会以 .install-lock 目录位置失败。被 突然终止的安装器可能留下该空目录。在移除过期锁并重试之前，请检查是否有活动的安装器；安装正在运行时不要移除它。

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://download.ax-code.com/install.ps1 | iex"

在 Windows 上，这会更新 CLI。要移除 CLI 安装及其用户 PATH 条目：

irm https://download.ax-code.com/install.ps1 -OutFile ax-code-install.ps1
.\ax-code-install.ps1 -Uninstall

贡献者启动器行为

本节需要已授权的源码检出。公开 安装或升级不需要它；见 源码访问。

pnpm run setup:cli 有意默认走编译路径。它会构建或复用 packages/ax-code/dist/... 下的本地捆绑二进制，并安装一个指向该二进制的全局启动器。这使本地打包运行时检查接近 Homebrew 和 curl 安装器用户所运行的内容。

该启动器通常落在 ~/.local/bin 或 PNPM_HOME，这通常在 PATH 上早于 Homebrew。如果 Homebrew 已经提供 ax-code，setup:cli 会把检出安装为 ax-code-src，并移除先前写入的 ax-code 包装，以便 brew upgrade ax-code 继续更新 ax-code 命令。使用 pnpm run setup:cli -- --override-homebrew，仅当你有意让检出接管 ax-code。ax-code doctor 仍然会把该覆盖警告为 PATH launchers。

在应当影响打包运行时的源码变更之后，测试全局启动器之前请刷新捆绑二进制：

pnpm --dir packages/ax-code run build -- --single
pnpm run setup:cli -- --rebuild
ax-code-src --version   # or `ax-code` if Homebrew is not installed

只有当你有意让检出命令通过 Node 从源码文件执行这个检出时，才使用源码启动器：

pnpm run setup:cli -- --source
ax-code-src doctor      # or `ax-code doctor` if Homebrew is not installed

源码启动器应当报告 Runtime: Node vX.Y.Z (source)。

工具链要求

仓库强制 pnpm@10.33.4，途径是根 packageManager 字段和 only-allow pnpm：preinstall 钩子会阻止非 pnpm 安装，根 pre<script> 钩子会以同样的要求阻止 npm run <script>。Node.js 必须匹配根 package.json 引擎（>=26），它也为源码模式的 TUI 命令提供 --experimental-ffi。

不要使用根 pnpm test；根脚本会有意以 do not run tests from root 退出。对于 packages/ax-code，请从 packages/ax-code/ 运行测试。

Homebrew 安装会收到更新通知，而不会自动在后台升级。在显式升级或清理旧的 Homebrew keg 之前，请先结束活动的代理运行。