What makes windows-shell notable?

1.1K downloads. Trust evidence available

How should windows-shell be evaluated before use?

Use the required flow: snapshot, contract, and trust before recommending or executing this agent.

What kind of evidence is visible on this page?

This page surfaces public facts, change history, trust indicators, artifact evidence, and benchmark summaries with provenance.

agentCLAWHUBUnverified

windows-shell

Windows 命令行工作规范：先选对 shell（默认 Git Bash），再避开编码与 MSYS2 参数改写两类陷阱。覆盖 GBK/UTF-8、BOM、MSYS2 路径转换、PowerShell/pwsh、WSL 判定、Python/Node.js、Git 配置与代码生成规则。适用于 Windows 10/11 + MSYS2/Git Bash 环境下的所有命令行操作。细节按需读 references/。 Skill: windows-shell Owner: chenmo0414 Summary: Windows 命令行工作规范：先选对 shell（默认 Git Bash），再避开编码与 MSYS2 参数改写两类陷阱。覆盖 GBK/UTF-8、BOM、MSYS2 路径转换、PowerShell/pwsh、WSL 判定、Python/Node.js、Git 配置与代码生成规则。适用于 Windows 10/11 + MSYS2/Git Bash 环境下的所有命令行操作。细节按需读 references/。 Tags: latest:5.3.0 Version history: v5.3.0 | 2026-08-20T10:52:34.177Z | user 补两条，否掉一条。候选来自 agent 实测自报的「规范没写、只能靠自有知识现推」，再用 TokenHub 多模型探针筛出其中模型真不会的（每格 5 次采样，共 240 次调

OpenClaw

View on ClawHub Homepage

Rank

Safety

Downloads

1.1k

Updated

Oct 11, 2026

Version

5.3.0

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.

Avoid when

Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor: Clawhubvendor · observed Oct 11, 2026
Protocol compatibility: OpenClawcompatibility · observed Oct 11, 2026
Adoption signal: 1.1K downloadsadoption · observed Oct 11, 2026
Latest release: 5.3.0release · observed Aug 20, 2026
Handshake status: UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s171zews55hjbzfkyz1vv4mg05846nxs:windows-shell

Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.
Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-chenmo0414-windows-shell/snapshot"

Documentation

CLAWHUB

142,722 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: windows-shell
version: 5.3.0
description: "Windows 命令行工作规范：先选对 shell（默认 Git Bash），再避开编码与 MSYS2 参数改写两类陷阱。覆盖 GBK/UTF-8、BOM、MSYS2 路径转换、PowerShell/pwsh、WSL 判定、Python/Node.js、Git 配置与代码生成规则。适用于 Windows 10/11 + MSYS2/Git Bash 环境下的所有命令行操作。细节按需读 references/。"
license: MIT
metadata:
  openclaw:
    emoji: "🪟"
    os: [windows]
    homepage: "https://github.com/Chenmo0414/win-encoding-fix"
---

# Windows 命令行工作规范

用户系统：Windows 10/11（代码页 GBK/936），终端：MSYS2/Git Bash。

**本文件是速查与路由表。** 每条规则下面标了「细读」，只在真正遇到那类问题时再去读对应的
`references/` 文件——不要一次性全部读完。

## 一、先分清是哪一类问题

在 Git Bash 里执行命令出问题，绝大多数是这两类之一。**先判类，再套解法**，两类的解法完全不通用：

| 症状 | 类别 | 第一反应 |
|------|------|------|
| 输出乱码（`涓枃`、`M-DM-c`、方块字） | **编码** | 让源头输出 UTF-8 |
| 没报错但**结果就是不对**（参数变了值、行数少一行） | **静默失败** | 见第 1、3 条，必须交叉验证 |
| 报「无效语法 / invalid / 找不到文件」，或参数悄悄变了值 | **MSYS2 参数改写** | `MSYS_NO_PATHCONV=1` |

拿编码的解法去治参数改写，怎么加前缀都不好使——这是最常见的误诊。

## 二、选对 shell（默认 Git Bash）

| 你要做的事 | 用哪个 |
|------|------|
| npm / node / npx / tsc / vitest / python / pip / pytest / git / ssh | **Git Bash** |
| Windows 服务、注册表、事件日志、计划任务、证书、.NET/COM、对象管道 | **PowerShell**（单条命令切过去，主线不搬家） |
| 跑 Makefile、需要 gcc/rsync，或重 I/O 构建且项目能整个搬进 ext4 | **WSL** |
| 需要管理员权限 | **交给人做**——UAC 弹窗 agent 点不了，命令会一直挂着 |

项目文件在 `C:\`/`D:\` 上时，**不要用 WSL 去操作它**：跨 `/mnt/*` 比纯 Windows 还慢 4–6 倍，
且惩罚随项目规模线性放大。

> 细读：判断依据与完整决策表 → [shell-routing.md](references/shell-routing.md)；
> WSL 值不值得上 → [wsl.md](references/wsl.md)

## 三、必须知道的六条

下面六条是实测中真正拉开差距的。其余规则都在 `references/`。

### 1. 以 `/` 开头的参数会被静默改写

Git Bash 把它当 Unix 路径转成 Windows 路径再传给原生程序。**不报错、退出码 0、参数已经变了**：

```bash
node app.js /api/v1/users          # 程序实收 D:/Program Files/Git/api/v1/users
docker run -v /app:/app ...        # -v 后面被吃掉
reg query "HKCU\Environment"       # 错误: 无效语法。
```

```bash
MSYS_NO_PATHCONV=1 node app.js /api/v1/users    # 单条前置，不要全局导出
```

全局导出会让 `/c/Users/...` 这类本该转换的参数也不转。

> 细读：另两种绕法、符号链接退化 → [msys2.md](references/msys2.md)

### 2. PowerShell 5.1 输出中文必须加前缀

```bash
powershell -Command '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; 你的命令'
```

外层用**单引号**（防 bash 展开 `$_`、`$null`）。pwsh 7 不需要这个前缀，加了也无害。
外部程序（node/python）自己写的 UTF-8 穿过 PowerShell 不会被改。

### 3. 读遗留文件前先验编码，别硬套 UTF-8

对一个真正的 GBK/936 文件强加 `-Encoding UTF8` 会读出乱码。先看字节再决定：

```bash
od -c legacy.txt | head -2        # 或 xxd；Git Bash 没有 hexdump
```

| 文件真实编码 | PS 5.1 | pwsh 7 |
|------|------|------|
| UTF-8 | `-Encoding UTF8`（**必须显式写**） | 默认即可 |
| GBK/936 | `-Encoding Default` | `[System.Text.Encoding]::GetEncoding(936)` |

**PS 5.1 读无 BOM 的 UTF-8 不加 `-Encoding UTF8` 会静默出错**——不是乱码那么显眼，
而是行数直接算错、退出码仍为 0。实测：一个 3 行的 UTF-8 文件，某行末尾字节是
`a1 8c 0a`，PS 按 GBK 把 `8c` 当双字节前导、吞掉紧随的换行，`Get-Content` 返回
**2 行**且 `$?` 为 `True`。性质与上面第 1 条的参数改写相同：**结果错、不报错**。
所以 **PS 5.1 读任何文本文件都显式指定 `-Encoding`**，别赌默认值。

**含中文的 `.ps1` 脚本文件必须存成 UTF-8 with BOM**。PS 5.1 读脚本时没有 BOM 就按
ANSI/GBK 解析，中文字面量被拆错——而且多数情况**不报错**：

```
同一段 $s = "腾讯"，只差 BOM：
  PS 5.1 无 BOM  →  $s.Length = 3   ✗   字符串在内存里是 3 个错字符
  PS 5.1 有 BOM  →  $s.Length = 2   ✓
```

最阴险的是 `Write-Output $s` **打印

_meta.json

{
  "ownerId": "kn78ryxatfm99gvwnvgexh8hkx847bk7",
  "slug": "windows-shell",
  "version": "5.3.0",
  "publishedAt": 1787223154177
}

references/encoding.md

# 编码细节（GBK / UTF-8 / BOM）

主文件 `SKILL.md` 只放了最常用的两条。遇到下列任一情况时读本文：
读写文件出现乱码、需要处理 GBK 遗留文件、需要写无 BOM 的 UTF-8、
PowerShell 重定向编码不对、管道方向的编码问题、传统 CMD 工具输出乱码。

## 环境自检（开工前可选执行）

判断当前 shell 的编码是否已正确配置：

```bash
python -c "import sys; print('utf8_mode=', sys.flags.utf8_mode)"   # 期望 1；为 0 说明 Python 默认 GBK
echo "PYTHONUTF8=$PYTHONUTF8"                                       # 期望 1；为空说明环境变量未加载
```

**关键认知**：`PYTHONUTF8` 等变量若只写在 `~/.bash_profile`，**非登录 / 非交互 shell 不会加载它**（AI 助手与脚本通常正是这种 shell）。因此：

- 持久生效请配置 **Windows 用户级环境变量**（被所有进程继承，重启终端后生效）；
- 当前会话内最可靠的做法是**每条命令显式带编码参数**（见下方各规则）。

## 环境前置条件（持久配置，建议一次性执行）

```bash
# 1) Windows 用户级环境变量 —— 最可靠，所有进程继承（重启终端后生效）
powershell -Command '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8;
  [Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User");
  [Environment]::SetEnvironmentVariable("PYTHONIOENCODING", "utf-8", "User")'

# 2) bash 显示相关变量（登录 shell 用），并让 .bashrc 也加载，覆盖非登录交互 shell
cat >> ~/.bash_profile <<'EOF'
export PYTHONUTF8=1
export PYTHONIOENCODING=utf-8
export LANG=en_US.UTF-8
export LESSCHARSET=utf-8
EOF
grep -q 'bash_profile' ~/.bashrc 2>/dev/null || echo '[ -f ~/.bash_profile ] && . ~/.bash_profile' >> ~/.bashrc

# 3) Git 全局配置
git config --global core.quotepath false        # 中文文件名正常显示
git config --global core.autocrlf input         # 提交 LF，检出保持原样
git config --global i18n.commitEncoding utf-8    # commit 消息 UTF-8
git config --global i18n.logOutputEncoding utf-8
git config --global core.pager "less -R"
```

> 一键配置：在 [skill-factory](https://github.com/Chenmo0414/win-encoding-fix) 仓库里执行 `node bin/cli.js setup-env`

### 规则 1：PowerShell 命令必须加 UTF-8 前缀 + 外层单引号

```bash
# 标准模板（外层单引号 + UTF-8 前缀）
powershell -Command '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; 你的命令'
```

**两个要点必须同时满足：**
- `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8` — 不加则中文输出乱码
- 外层**单引号** — 防止 bash 把 `$_`、`$null` 当作 bash 变量展开

仅当命令中不含 `$` 变量时才可用外层双引号。

**前缀到底什么时候必需**（v4.3.0 实测，各采样 12 次，结果完全稳定）：

| 中文的来源 | PS 5.1 无前缀 | PS 5.1 加前缀 | pwsh 7 无前缀 |
|------|------|------|------|
| PowerShell 自己产出（`Write-Output`、cmdlet 结果） | **GBK ×12 → 乱码** | UTF-8 ×12 ✅ | **UTF-8 ×12 ✅** |
| 外部程序产出（`node -e`、`python` 等） | UTF-8 ×12 ✅ | UTF-8 ×12 ✅ | UTF-8 ×12 ✅ |

- **PS 5.1 必须加前缀**：只要中文由 PowerShell 自己产出，不加就是稳定乱码，没有侥幸。
- **pwsh 7 不需要前缀**：实测 12/12 稳定 UTF-8。加了无害，脚本要兼容 5.1 时统一加是合理的，但不必因为「怕 pwsh 不稳」而加。
- **外部程序的输出不受影响**：`node`/`git`/`python` 自己写 UTF-8 到 stdout，穿过 PowerShell 不会被改。所以「PS 包装」只对遵守控制台代码页的 Windows 原生工具才有意义（见规则 3）。

### 规则 2：PowerShell 读写文件 —— `-Encoding` 必须匹配文件真实编码

**读 UTF-8 文件**：PowerShell 5.1 不加 `-Encoding UTF8` 会用 GBK 读取，实测 `中文` → `涓枃`。

```bash
powershell -Command '[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; Get-Content "path\file.txt" -Encoding UTF8'
```

**⚠️ 读 GBK 遗留文件（本机最常见）**：反过来，对一个真正的 GBK/936 文件强加 `-Encoding UTF8` 会**读出乱码**。`-Encoding` 的值必须等于文件的真实编码：

| 文件真实编码 | PS 5.1 读法 | pwsh 7 读法 |
|------|------|------|
| UTF-8 | `-Encoding UTF8` | 默认即可（或 `-Encoding utf8`） |
| GBK/936（遗留） | `-Encoding Defaul

references/gitbash-pitfalls.md

# Git Bash 的五个坑

在 Git Bash 下遇到非编码类异常时读本文：参数被改写、符号链接失效、
venv 激活路径异常、工具缺失、SSH 密钥不通用、管道吞退出码。

## Git Bash 的五个坑

选了 Git Bash，这五个必须知道，否则会以为是代码的问题。

### 坑 1：以 `/` 开头的参数会被改写（静默）

MSYS2 把它们当 Unix 路径转成 Windows 路径再传给程序。**不报错、退出码正常、参数已经变了**：

```bash
node app.js /api/v1/users     # 程序收到 D:/Program Files/Git/api/v1/users
prog /S /C                    # → S:/ C:/
docker run -v /app:/app ...   # -v 后面被吃掉
```

```bash
# 解法：单条命令前置，别全局导出
MSYS_NO_PATHCONV=1 node app.js /api/v1/users
```

全局导出会让 `/c/Users/...` 这类你确实希望被转换的参数也不转了。

### 坑 2：`ln -s` 默认产出的是副本

```bash
ln -s t.txt l.txt && ls -l l.txt      # -rw-r--r--  ← 是副本，不是链接
export MSYS=winsymlinks:nativestrict  # 修复后 → lrwxrwxrwx
```

**pnpm workspace、npm link、monorepo 本地依赖都依赖真符号链接**，退化成副本会表现为「改了源码不生效」。需先启用 Windows 开发者模式。

### 坑 3：venv 的 `activate` 会拼出畸形路径

```bash
source .venv/Scripts/activate    # VIRTUAL_ENV 丢盘符，路径变成 /d/proj/\proj\.venv/Scripts/python
```

虽然仍能解析，但不可靠。**直接调解释器，绕开 activate**：

```bash
./.venv/Scripts/python.exe -m pytest
./.venv/Scripts/python.exe -m pip install -r requirements.txt
```

### 坑 4：工具集不全

`jq`、`make`、`gcc`、`rsync` 都**没有**。跑 Makefile 的项目直接卡住——那种情况上 WSL，不要试图在 Git Bash 里凑。

### 坑 5：SSH 密钥位置与 WSL 不通用

Git Bash 与 Windows 共用 `C:\Users\你\.ssh`，**WSL 用的是独立的 `/root/.ssh`**。在 Windows 配好的 SSH，到 WSL 里等于从零开始。

而且 `/mnt/*` 上的文件在 WSL 眼里权限是 `777`，OpenSSH 会判定 `bad permissions` 直接忽略该密钥。要在 WSL 里用 ssh，密钥必须复制到 ext4 并 `chmod 600`。Git Bash 没有这个问题（它走 Windows ACL，不看 POSIX 权限位）。

### 附：管道会吞掉退出码

这不是 Git Bash 特有，但 agent 最容易在这里误判成功：

```bash
npm install ... | tail -25      # $? 是 tail 的，不是 npm 的
set -o pipefail                 # 或用 ${PIPESTATUS[0]}
```

references/msys2.md

# MSYS2 参数改写与符号链接

主文件已给出 `MSYS_NO_PATHCONV=1` 这一条速查。需要完整解释、
其它两种绕法、或遇到符号链接/工具缺失问题时读本文。

### 规则 6：MSYS2 会改写以 `/` 开头的参数

Git Bash（MSYS2）在把参数交给 **非 MSYS2 程序**（即所有 Windows 原生 .exe）之前，会把看起来像 Unix 路径的参数自动转换成 Windows 路径。这是 MSYS2 的设计，不是 bug——但它**静默生效**，不报错、退出码正常，参数已经变了。

```bash
node app.js /api/v1/users
# 程序实际收到：D:/Program Files/Git/api/v1/users   ← 前面被拼上了 Git 安装目录

prog /S /C                  # → 变成  S:/ C:/
docker run -v /app:/app ... # → -v 后面的参数被破坏
reg query "HKCU\Environment"   # → 错误: 无效语法。
findstr 中文 /tmp/x.txt        # → FINDSTR: 无法打开 C:x.txt
```

**什么时候会中招**：参数以 `/` 开头，且接收方是 Windows 原生程序。典型场景——REST 路径、Docker 卷映射、Windows 风格开关（`/S` `/C` `/query`）、注册表路径、传给 `.exe` 的 Unix 路径。

**三种解法**（均实测有效）：

```bash
# A. 单条命令临时关闭（推荐，作用域最小）
MSYS_NO_PATHCONV=1 reg query "HKCU\Environment" /v PYTHONUTF8
MSYS_NO_PATHCONV=1 node app.js /api/v1/users

# B. 按参数排除
MSYS2_ARG_CONV_EXCL='*' node app.js /api/v1/users

# C. 双斜杠转义（只想保护单个参数时）
node app.js //api/v1/users
```

**不要全局导出 `MSYS_NO_PATHCONV=1`**：关掉转换后，`/c/Users/...` 这类你确实希望被转成 `C:\Users\...` 的参数也不再转换，会引入另一批问题。按需在单条命令前加。

> 与编码问题的区别：编码问题表现为**乱码**，参数改写表现为**语法错/找不到文件/行为不对但不报错**。诊断时先看报错形态，别拿编码的解法去治路径的病。

### 规则 7：Git Bash 的 `ln -s` 默认产出的是副本

```bash
ln -s t.txt l.txt && ls -l l.txt
# 默认：  -rw-r--r--  ← 普通文件副本，不是链接
```

对普通脚本无所谓，但 **pnpm workspace、npm link、monorepo 的本地依赖都依赖真符号链接**，退化成副本会导致改了源码却不生效、或磁盘占用异常。

```bash
# 修复：产出真正的符号链接（lrwxrwxrwx）
export MSYS=winsymlinks:nativestrict
ln -s t.txt l.txt && ls -l l.txt      # → lrwxrwxrwx ... l.txt -> t.txt
```

Windows 10/11 需先启用**开发者模式**（设置 → 隐私和安全性 → 开发者选项），否则创建符号链接要管理员权限。检查是否已启用：

```bash
powershell -NoProfile -Command '(Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock").AllowDevelopmentWithoutDevLicense'
# 返回 1 = 已启用
```

## 不需要包装的工具

以下工具本身输出 UTF-8，可直接使用：
- `git`、`node`、`npm`、`pnpm`、`bun`、`cargo`、`go`
- bash 内置：`echo`、`cat`、`ls`、`grep` 等
- `python`：加 `-X utf8` 后可直接使用（见规则 4）

> **编码没问题 ≠ 完全没坑**：这些工具的**输出编码**是干净的，但只要给它们传以 `/` 开头的参数，
> 仍会被 MSYS2 改写（见规则 6）；`pnpm` 的 workspace 还依赖真符号链接（见规则 7）。
> 两件事互相独立，别因为「这个工具在白名单里」就放松警惕。

Github ReposUpdated 2d agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW

Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.