先为运行应用的操作系统和 CPU 选择 Paneflow 安装包，再在项目所在的 shell 中安装编码智能体。终端应用兼容，并不代表所有智能体、运行时和 shell 的组合都兼容。

## Paneflow 0.17.4 安装矩阵

以下文件于 2026 年 10 月 1 日与 [0.17.4 发行版](https://github.com/arthjean/paneflow/releases/tag/v0.17.4)核对。文件可用不等于在每台机器上完成安装测试。Paneflow 是采用 GPL-3.0-or-later 许可的免费自由软件。

| 操作系统 | CPU | 安装参考 | 运行条件 |
| --- | --- | --- | --- |
| Linux | x86_64 或 ARM64（`aarch64`） | [Linux](/zh-Hans/docs/installation/linux)：AppImage、`.deb`、`.rpm`、`.tar.gz` | 可用的 Vulkan 驱动与加载器；仍需满足软件包或独立安装的依赖。 |
| macOS 13+ | Apple Silicon（`aarch64`） | [macOS](/zh-Hans/docs/installation/macos)：`.dmg` 或 Homebrew | Apple Silicon 构建，不是 Intel 二进制文件。 |
| Windows 10 1809+ 或 Windows 11 | x64（`x86_64`） | [Windows](/zh-Hans/docs/installation/windows)：`.msi` | 可用的 GPU 驱动、DirectX 11 功能级别 10+、ConPTY 终端运行时。 |
| macOS Intel | x86_64 | 此版本没有原生文件 | 不应将 Apple Silicon DMG 视为兼容安装包。 |
| Windows ARM | ARM64 | 此版本没有原生文件 | 不应将 x64 MSI 视为经过验证的 ARM 安装方案。 |

矩阵依据该版本的[构建目标](https://github.com/arthjean/paneflow/blob/v0.17.4/.github/workflows/release.yml)、[Linux 软件包依赖](https://github.com/arthjean/paneflow/blob/v0.17.4/src-app/Cargo.toml)和 [Windows 运行时参考](https://github.com/arthjean/paneflow/blob/v0.17.4/docs/user/installation/windows.md)。Windows 镜像文档保留了旧安装包示例，文件名应以当前安装页面为准。AppImage 打包的是应用，不会补上缺失的 GPU 驱动。

## 在目标 shell 中检查智能体

| 智能体 | 本指南实际检查内容 | 官方平台说明 |
| --- | --- | --- |
| Claude Code | Windows x64：`claude --version` 返回 2.1.286；`claude --help` 确认交互式入口 | [安装说明](https://code.claude.com/docs/en/setup)涵盖 macOS、Linux、原生 Windows 和 WSL。在原生 Windows 上，Git for Windows 提供 Bash；未安装时，当前文档说明使用 PowerShell 工具。该文档不支持原生 Windows 沙箱。 |
| Codex CLI | Windows x64：`codex --version` 返回 0.159.2；`codex --help` 确认交互式入口 | [CLI](https://github.com/openai/codex) 和 [Windows 沙箱](https://developers.openai.com/codex/windows/windows-sandbox)文档涵盖原生 Windows 与 macOS/Linux。推荐 Windows 11，更新后的 Windows 10 为尽力支持。原生沙箱设置可能需要管理员批准，并受设备策略影响。 |

智能体资料查阅于 2026 年 10 月 1 日。版本与帮助检查并不证明身份验证、模型执行、沙箱行为、所有 shell、Linux 或 macOS 均已验证。本指南未测试其他智能体。请将各智能体的权限与要求同 Paneflow 支持矩阵分开考虑。

## 原生 Windows 还是 WSL？

对于 Windows 仓库和工具，从开始菜单或原生 Windows shell 启动 MSI 安装的应用。在 Settings 中选择 shell，并确认智能体的 PATH。在 WSL 中安装智能体不会同时安装到 PowerShell，反之亦然。

如果 Linux 工具链已经位于 WSL2，就将仓库、依赖和智能体保留在该环境中。[Windows 安装参考](/zh-Hans/docs/installation/windows)说明了在 WSL2 中通过 WSLg 使用 Linux 构建的方式，图形要求仍然适用。在原生 Paneflow 面板中使用 WSL shell，与运行 Linux 应用是不同方案。不要从 WSL 主机 shell 启动原生 Windows 应用。本指南未执行这两种 WSL 配置。

Codex 当前的 [WSL 指南](https://developers.openai.com/codex/windows/wsl)将其作为 Linux 工具链或原生沙箱无法满足需求时的选择，并不意味着 Windows 上所有智能体都必须使用 WSL。Claude Code 在两种环境中的沙箱能力也不同，应遵循其安装参考，不能假定终端提供沙箱隔离。

## 定位故障所在层

1. 在系统信息中确认操作系统和 CPU。macOS Intel 或 Windows ARM 的边界是没有原生文件；请参阅[安装参考](/zh-Hans/docs/installation)，不要猜测安装包。
2. 如果 Paneflow 无法打开窗口，检查平台安装文档及 GPU、运行时要求，再参阅[故障排查](/zh-Hans/docs/troubleshooting)。更换智能体不能修复缺失的显卡驱动。
3. 如果应用打开但找不到 `claude` 或 `codex`，就在该面板运行版本命令。检查 PATH，以及智能体安装在原生 Windows 还是 WSL 中，并遵循智能体自身的安装说明。
4. 如果 CLI 能启动但无法验证身份或执行模型任务，检查其凭据、权限、网络和服务提供商访问。重新安装 Paneflow 不会补齐这些前提。

应用和智能体都能在目标环境运行后，可用 [worktree 参考文档](/zh-Hans/docs/worktrees)分离并行更改。安装细节保留在平台参考中，无需为每个发行版或智能体复制类似步骤。