Windows 上的 Rez

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install rez-windows-platform
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 rez-windows-platform。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Windows 上的 Rez 介绍了平台特有的行为，这些行为可能导致同一个包或 resolve 在不同 Shell 和操作系统中的表现不同。内容涵盖 Rez 3.4.0 注册的四种 Windows Shell、默认 Shell 的选择方式，以及为什么 cmd 和 pwsh 使用分号，而 gitbash 使用冒号分隔列表型环境变量。
本 Openclaw Skills 指南为开发者提供实用工作流程，用于检查生成的 Shell 代码、编写可移植的包命令、诊断超过 260 个字符的 MAX_PATH 限制的路径，以及处理 Windows 隐式包和 CI 差异。在移植 Rez 包、调查仅在 Windows 上出现的故障，或验证跨 Shell 行为时，请使用本指南。

应用场景

了解 Rez 在 Windows 上支持哪些 Shell，以及为什么
bash
会被拒绝。
诊断在
cmd
、
pwsh
gitbash
中表现不同的
PATH
、
PYTHONPATH
或自定义列表变量。
无需启动目标 Shell 即可检查生成的 Shell 代码，包括从 Linux 构建机器检查。
调查仅在路径变得很深时才会失败的包安装或构建。
在 Windows 和 POSIX 系统之间移植包定义，避免硬编码分隔符或斜杠。
排查 Windows 变体在操作系统更新后停止解析的问题。
在 Windows CI 运行器上验证 Rez 安装路径、配置来源和命令可用性。

工作原理

识别平台和可用的 Shell。 使用 get_shell_types() 查询 Rez，而不要假设在 Linux 或 macOS 上注册的 Shell 在 Windows 上也可用。
确定选用的 Shell。 检查 default_shell；若为空，Rez 会检测当前 Shell，在 Windows 上通常是 powershell。使用 --shell 为单次调用指定一个已注册的 Shell。
检查环境变量操作。 使用 rex 列表操作，例如 append、prepend 和 set，而不要手动拼接路径。Rez 会为目标 Shell 选择合适的分隔符。
预览 Shell 输出。 运行 rez-interpret，并将 -f 设为 cmd、gitbash、powershell 或 pwsh。对于预览时应包含现有值的变量，添加 --pv。
检查路径约定和长度。 在包定义中使用可移植的正斜杠路径或 {root}；文件系统操作失败时，测量深层嵌套的绝对路径。
验证平台要求。 检查隐式包；选择特定操作系统变体时，优先使用 platform，而不是固定且容易受更新影响的 os 版本。
确认安装和配置。 使用 Rez 状态和配置来源命令，验证当前生效的可执行文件和配置文件，尤其是在 CI 中。

配置指南

将 Rez 安装到你打算使用的 Python 解释器中，并确保在 Windows 上该解释器的 Scripts 目录位于 PATH 中。托管 CI 工作流可以在安装 Rez 之前使用 actions/setup-python。
检查当前生效的安装和配置来源：
rez-status
rez-config --source-list packages_path
rez-config default_shell
使用 Python 检查已注册的 Shell：
python -c "from rez.shells import get_shell_types; print(get_shell_types())"
在 Windows 上，已注册的 Shell 为 cmd、gitbash、powershell 和 pwsh。为带有 Windows Shell 的 Rez 环境选择其中一种，例如：
rez-env foo --shell cmd
预览目标 Shell 的命令，而不启动该 Shell：
rez-interpret -c 'env.PATH.prepend("{root}/bin")' -f cmd
rez-interpret -c 'env.PATH.prepend("{root}/bin")' -f pwsh
rez-interpret --no-env -c 'env.FOO = "bar"' -f cmd
在 Windows 上为路径列表参数提供拼接值时，请使用分号。例如：rez-env --paths "C:/studio/packages;C:/studio/local" foo -o context.rxt。若要在受支持的 Windows 版本上全局启用长路径，请在 HKLM\SYSTEM\CurrentControlSet\Control\FileSystem 下将 LongPathsEnabled 设为 1，或应用相应的组策略；此操作需要重启。更改系统设置前，请遵循所在组织的 Windows 管理政策。

数据架构

Rez 在 Windows 上的特定行为围绕 Shell、路径列表、平台元数据和文件系统布局展开：
区域 结构或约定 实际影响
已注册的 Shell cmd、gitbash、powershell、pwsh bash 等 POSIX Shell 未在 Windows 上注册。
默认 Shell default_shell，然后是 system.shell 空的 default_shell 会回退到 Shell 检测；在 Windows 上通常为 powershell。
列表型环境变量 Shell 特定的生成代码 cmd 和 pwsh 使用 ; 拼接；gitbash 使用 : 拼接。这不仅适用于 PATH，也适用于其他列表变量。
路径约定 os.sep 为 \；os.pathsep 为 ; packages_path 是 Python 列表，而接受拼接路径列表的标志会使用平台路径分隔符。
文件系统仓库布局 //// 变体要求可能为每项要求增加一个目录，从而加深路径。
隐式包 ~platform、~arch 和 ~os 与固定可能在更新后改变的 Windows 操作系统版本相比，优先选择稳定的平台标识。
Rez 配置 按顺序加载的配置文件 rez-config --source-list 会报告 Rez 实际读取的文件及其路径。
长路径处理 Windows 扩展长度路径，例如 \?\C:... 和 \?\UNC... Rez 仅在特定情况下应用长路径处理；不要假设所有面向用户的操作都受其支持。
在可移植的包定义中使用正斜杠或 {root}，并让 rex 处理列表型环境变量。rez-interpret 可以输出特定 Shell 的代码，也可以提供与 Shell 无关的 dict 和 table 视图；它只打印输出，不会启动 Shell。

高级特性

跨 Shell 检查工具：
rez-interpret -f
从任意平台检查为 Windows Shell 生成的代码，无需启动这些 Shell。
现有值预览： --pv ，查看相对于环境变量现有值的前置或追加行为。
与 Shell 无关的输出：
rez-interpret
dict
table
格式，在不指定目标 Shell 的情况下比较结果。
可移植的环境构建：
使用 rex 的
append
、
prepend
set
操作，让 Rez 选择合适的路径列表分隔符。
长路径诊断：
测量绝对路径长度，并区分由路径深度导致的
MAX_PATH
故障与分隔符或引号问题。Rez 3.4.0 提供
rez.utils.filesystem.windows_long_path()
，但仅在特定情况下应用。
变体兼容性：
~platform
、
~arch
~os
；若设备群需要统一平台名称，使用
platform_map
；若更新不应导致变体失效，则避免固定精确的操作系统版本。
配置来源追踪：
rez-config --source-list
，找出某项设置所用的配置文件及其顺序。
Windows CI 就绪性：
将 Rez 的 Python
Scripts
目录保留在
PATH
中，考虑运行器 Shell 的引号差异，并且不要假设包测试可以调用 POSIX Shell。
缓解路径过深：
缩短仓库根路径和包名称，在适当情况下减少变体要求，或使用 Rez 短链接限制嵌套安装路径。

name: rez-windows-platform description: "Running rez on Windows — why only cmd, gitbash, powershell and pwsh are registered there and how the default is picked, the path-separator trap where cmd and pwsh join with ';' while gitbash joins with ':', backslash versus forward slash in generated shell code, the 260-character MAX_PATH limit and why variant install paths exceed it, the platform/arch/os implicit packages, using rez-interpret as a cross-shell oracle without launching a shell, install and config-file layout, and CI differences. Use when a package or resolve behaves differently on Windows, when porting a package across operating systems, when a deep path fails to read or write, or when a one-liner works in bash and fails in cmd. Covers Rez 3.4.0."

Rez on Windows

One-sentence summary: on Windows rez registers only cmd, gitbash, powershell and pwsh as shells, and those shells disagree about the path separator — cmd and pwsh join lists with ; while gitbash joins them with : — which is why the same package.py can produce a working PATH in one shell and a broken one in another.

Skill scope: the Windows-specific differences. For the commands() body and the rex API in general see rez-package-commands; for package.py attributes see rez-package-definition; for config layering and plugin discovery see rez-config-plugins; for a resolve that fails on any platform see rez-resolve-troubleshooting.

Platform note. Every fenced block in this skill is tagged with the shell it belongs to (powershell, bat, ```bash). Commands tagged powershell or bat are Windows-only and will fail on Linux or macOS, where those shells are not registered. The rez-interpret examples are safe to run anywhere — it only prints text, never launches a shell.

Which shells exist on Windows

Rez ships shell plugins for bash, sh, csh, tcsh, zsh, cmd, gitbash, powershell and pwsh, but only the ones valid for the current platform are registered. On Windows:

cmd, gitbash, powershell, pwsh

The POSIX shells are not registered there, so rez-env --shell bash is not a valid value on Windows and vice versa. Ask rez rather than assuming, because the answer is platform-dependent:

from rez.shells import get_shell_types

print(get_shell_types()) # ['cmd', 'gitbash', 'powershell', 'pwsh'] on Windows

How the default shell is chosen

The order is default_shell, then system.shell:

rez-config default_shell

default_shell is empty ('') out of the box, in which case rez falls back to detecting the current shell — on Windows that is typically powershell. There is no default_windows_shell setting in rez 3.4.0; default_shell is the only knob, and it applies on every platform.

To target a shell for one invocation:

# Windows only — 'cmd' is not a registered shell on Linux or macOS

rez-env foo --shell cmd

REM Windows only

rez-env foo --shell cmd

The path separator trap

This is the difference that breaks real packages. The same rex produces different text per shell:

rez-interpret -c 'env.MY_PATH.prepend("C:/pkgs/foo/bin")' -f cmd --pv MY_PATH
rez-interpret -c 'env.MY_PATH.prepend("C:/pkgs/foo/bin")' -f pwsh --pv MY_PATH
rez-interpret -c 'env.MY_PATH.prepend("C:/pkgs/foo/bin")' -f gitbash --pv MY_PATH

With MY_PATH already set, the generated code is:

Shell Generated line Separator

cmd set MY_PATH=C:\pkgs\foo\bin;C:\Program Files\Git\usr\bin;... ;
pwsh Set-Item -Path "Env:MY_PATH" -Value ("C:\pkgs\foo\bin;" + ...) ;
gitbash export MY_PATH="C:/pkgs/foo/bin:${MY_PATH}" :

Two things to take from it:

The list separator is ; under cmd and pwsh, and : under gitbash. A package.py that builds a list by hand — joining with : because it was written on Linux — produces a single unreadable entry on Windows. Use the rex list operations (append, prepend, set) and let rez pick the separator.
cmd and pwsh emit backslashes; gitbash keeps forward slashes. Both work in their own shell, so the difference only bites when you compare or string-match paths.

The separator applies to every list-valued variable, not just PATH — PYTHONPATH, LD_LIBRARY_PATH-style variables and any custom list behave the same way.

Backslashes, drive letters and path separators
os.sep is a backslash and os.pathsep is a semicolon on Windows, versus a forward slash and a colon on POSIX.
packages_path is a Python list, so it is immune to the separator problem — do not build a ;-joined string for it.
Flags that do take a joined path list use os.pathsep, so they take ; on Windows. This includes rez-env --paths and rez-search --paths:

# Windows only — the separator is ';' here, not ':'

rez-env --paths "C:/studio/packages;C:/studio/local" foo -o context.rxt

Paths inside a package.py should be written with forward slashes or with {root}, and joined with the rex API. A hard-coded backslash will not survive a move to Linux, and a hard-coded colon will not survive a move to Windows.
Path length: the 260-character limit

Win32 caps a path at 260 characters (MAX_PATH) unless long paths are enabled. Rez paths are deep by construction, so this is a real failure mode and not a theoretical one.

The depth comes from how a variant is laid out. For the filesystem repository the install path is ////, and the variant subpath nests one directory per variant requirement. A package with variants = [["python-3.11", "pytest-7", "six"]] installs under:

python-3.11\pytest-7\six

Add a deep shared-storage root, a build directory during rez-build, and the package's own internal tree, and the total passes 260 long before the layout looks unreasonable. A realistic studio example — a UNC share, a long show name, an eight-requirement variant and a nested Python package — measures 316 characters, 56 over the limit.

Rez 3.4.0 has a helper for this, rez.utils.filesystem.windows_long_path(), which prefixes the extended-length marker to lift the limit.

\?\C:\pkgs\foo # local path
\?\UNC\server\share\x # UNC path

It is applied internally and selectively — notably in the retry path of robust_rmtree — so do not assume it covers the operation that just failed for you. Most user-facing operations still go through ordinary paths.

To enable long paths system-wide on Windows 10 1607 and later, set the registry value LongPathsEnabled to 1 under HKLM\SYSTEM\CurrentControlSet\Control\FileSystem, or apply the equivalent Group Policy ("Enable Win32 long paths"). A reboot is required. The extended-length prefix itself only works on absolute paths with no forward slashes and no . or .. components, which is why rez applies it to os.path.abspath() output rather than to the path as written.

Telling a length problem from a separator problem

Both surface as "rez cannot find or write this path", and they are easy to confuse. Two cheap ways to separate them:

Length: the failure tracks the path's depth, not its content. Shortening the repository root or the package name makes it disappear. Measure it directly — python -c "import os; print(len(os.path.abspath(
)))" — and compare against 260.
Separator: the failure tracks content, not depth. A list variable arrives as one long entry, or a path with the wrong slashes. The same path at the same length works in another shell.

If the path is under 260 and still fails, it is not the length limit — go back to the separator and quoting sections above.

Where to shorten

When you cannot enable long paths fleet-wide, the cheapest wins are, in order:

Move the package repository to a shallower root (C:\packages beats a deep UNC share).
Shorten the package name — it appears in every variant path.
Reduce the number of variant requirements, or let rez shortlink them.
Avoid long version strings; 1.14.3+local.2026.10.05 costs more than 1.14.3.

The platform implicit packages

Windows resolves add implicit packages that carry the OS identity. On a Windows 11 machine:

rez-config implicit_packages

• ~platform==windows
• ~arch==AMD64
• ~os==windows-10.0.26100.SP0

Three consequences:

Any variant that must differ per OS keys off platform or os, not off sys.platform at module scope — see rez-package-pitfalls for why module scope is evaluated on the build machine.
The os version string is a moving target: a Windows feature update changes ~os, so a variant pinned to an exact os version stops resolving after an upgrade. Prefer platform.
platform_map (default {}) can normalise a platform name across machines when a fleet reports slightly different values.
rez-interpret: the cross-shell oracle

rez-interpret executes rex and prints the resulting shell code for any registered shell. It never launches one, which makes it the cheapest way to answer "what will this actually do on cmd?" — including on a Linux build machine that has no cmd at all.

rez-interpret -c 'env.PATH.prepend("{root}/bin")' -f cmd
rez-interpret -c 'env.PATH.prepend("{root}/bin")' -f pwsh
rez-interpret --no-env -c 'env.FOO = "bar"' -f cmd

-f accepts cmd, gitbash, powershell, pwsh, plus dict and table for a shell-independent view. --pv marks variables that should be updated rather than overwritten on first reference — without it, a prepend against a variable rez cannot see looks like a plain overwrite, which is the most common way to misread this output.

Use it when reviewing a package.py for cross-platform behaviour, and when a one-liner works in bash but not in cmd.

Install and config layout

Rez is installed into the Python it was pip-installed into, so on Windows the entry points land in that interpreter's Scripts directory rather than a bin directory. Confirm which rez you are running and where its config comes from:

rez-status
rez-config --source-list packages_path

--source-list prints the config files rez actually read, in order, with real paths. On Windows those are drive-lettered paths such as C:\Users\AppData\Local\Programs\Python\Python312\Lib\site-packages\rez\rezconfig.py. It is the fastest way to prove a setting is coming from the file you think it is.

CI differences

Rez needs the Python it was installed into on PATH. On Windows hosted runners, prefer actions/setup-python and install rez into it, so the Scripts directory is already on PATH.
Build and test steps are the same commands — rez-build --install, then rez-test — but the shell the runner uses to invoke them differs, which changes quoting. A request with a range (rez-env 'foo