安装方式
手动下载安装
下载 ZIP 后解压到技能目录即可安装。若在桌面客户端 WebView中直接下载出现异常，本站会改为提示页 + 原始链接，请按页内说明操作。
下载 ZIP (shub-powershell-sandbox-v1.0.0.zip)触发指令
/powershell-sandbox-pow
跨平台安装指引
该技能声明兼容以下 1 个平台，将 ZIP 解压到对应目录即可被识别。
unzip shub-powershell-sandbox-v1.0.0.zip -d ~/.claude/skills/
目录不存在时请先
mkdir -p 创建；启用 Skill 后请重启对应 Agent 让配置生效。
使用指南
PowerShell 沙箱
围绕 PowerShell 沙箱：在受限环境运行不可信或实验性脚本；策略与 Constrained Language 见 SKILL.md。 无需在每次任务前把零散英文说明手工拼进上下文，也 减少 与客户端默认行为脱节的试错；具体命令、钩子与 JSON 参数仍以 ZIP 包内 SKILL.md 为权威。下文结构与站内 MCP CLI 类专题稿相同：何时用、前置、流程、速查与故障。
何时使用
- 在受限环境运行不可信或实验性脚本
- 策略与 Constrained Language 见 SKILL.md
- 已获取本技能 ZIP，并准备在 Claude Code / OpenClaw 中按 SKILL.md 挂载。
- 希望用中文专题稿快速判断「该不该启用」，再深入英文 SKILL 查参数与边界。
- 需要与团队对齐同一套触发方式、目录约定或回调格式时。
前置条件
- 通用：可运行 Claude Code 或文档要求的客户端；有可读写的项目工作区（或 SKILL.md 指定的沙箱目录）。
- 权威细节：API Key / OAuth、钩子路径、环境变量以 ZIP 内 SKILL.md 为准。
典型流程
- 从 ClawHub / 站内分发获取技能 ZIP，校验版本与校验和（若提供）。
- 阅读 SKILL.md 的安装段落：目录落点、客户端类型（Claude Code / OpenClaw / 脚本）。
- 用文档中的最小示例完成第一次调用（单文件修改、单次查询或单次委派）。
- 确认工作目录、权限边界与输出路径后，再处理多文件或长耗时任务。
- 需要回调 / Webhook / 通知时，按 SKILL.md 配置端点并在测试环境先验通。
与 ZIP / SKILL.md 的关系
站内专题稿与 MCP CLI 类 oss 稿同样：概括何时用、怎么接、怎么排错；命令模板、钩子名、JSON 字段、版本矩阵一律以 ZIP 内 SKILL.md 与 ClawHub 上游为准。
命令示例（摘自包内 SKILL.md）
以下为从上游 SKILL.md（或入库正文）自动抽取的终端/脚本片段；路径、环境变量与参数以当前 ZIP 与官方说明为准。
ClawHub slug：powershell-sandbox（安装命令以 SKILL.md / claw CLI 为准）。
# 执行脚本（默认 30 秒超时）
.\src\sandbox.ps1 -ScriptPath "C:\path\to\script.ps1"
# 自定义超时时间
.\src\sandbox.ps1 -ScriptPath "script.ps1" -TimeoutSeconds 60
# 指定工作目录
.\src\sandbox.ps1 -ScriptPath "script.ps1" -WorkingDirectory "C:\workspace"
# 允许网络访问（谨慎使用！）
.\src\sandbox.ps1 -ScriptPath "script.ps1" -AllowNetwork
# 通过 exec 调用
exec(
command: '.\skills\powershell-sandbox\src\sandbox.ps1 -ScriptPath "C:\Users\99236\.openclaw\workspace\scripts\user-script.ps1"',
timeout: 60
)
$job = Start-Job -ScriptBlock $script
$completed = Wait-Job -Job $job -Timeout $TimeoutSeconds
if (-not $completed) {
Stop-Job -Job $job
Write-Error "执行超时！"
}
# test-safe.ps1
Write-Host "Hello from sandbox!"
$numbers = 1..10
$sum = ($numbers | Measure-Object -Sum).Sum
Write-Host "Sum of 1-10: $sum"
.\src\sandbox.ps1 -ScriptPath "test-safe.ps1"
# test-dangerous.ps1
Invoke-WebRequest -Uri "https://example.com"
.\src\sandbox.ps1 -ScriptPath "test-dangerous.ps1"
# test-timeout.ps1
Write-Host "Starting..."
Start-Sleep -Seconds 60
Write-Host "Done!"
.\src\sandbox.ps1 -ScriptPath "test-timeout.ps1" -TimeoutSeconds 30
# test-file.ps1
$content = Get-Content "data.txt"
Write-Host "File content: $content"
Set-Content "output.txt" "Processed: $content"
站内入库时的触发命令（完整语义见 ZIP）：
# 使用本技能时可在对话中引用或执行上述指令；完整参数与示例见下载包内 SKILL.md。
/powershell-sandbox-pow
最佳实践
- 先 SKILL.md 再猜参数；站内专题稿不替代 schema 与必填字段说明。
- 委派任务时写清验收标准（命令、文件路径、测试命令），减少来回追问。
- 长任务用文档推荐的回调 / 日志落盘代替高频轮询，省 Token 也省机器负载。
- 多技能同时启用时，注意钩子加载顺序与重复工具调用（以 SKILL.md 冲突说明为准）。
调试与排错
- 打开 stderr 与客户端日志；PTY/tmux 场景同时看面板最后几十行输出。
- 参数错误时对照 SKILL.md 中的 JSON/CLI 示例（引号、转义、工作目录）。
- 网络类失败：查代理、防火墙、MCP 传输方式（stdio / HTTP / SSE）。
速查
| 动作 | 说明 |
|------|------|
| 获取技能包 | ClawHub / 站内 ZIP，核对版本 |
| 权威步骤 | 优先阅读 ZIP 内 SKILL.md |
| 首次试跑 | 使用 SKILL.md 最小示例 |
| 验收 | 对照路径、测试命令或回调负载 |
常见故障
- 无输出或立即退出 → 工作目录错误、依赖未装、或 Claude Code 未登录；按 SKILL.md 自检清单执行。
- 权限被拒绝 → 检查沙箱路径、
--permission-mode与工具白名单。 - 与简介不符 → 以英文 SKILL 与上游仓库为准，站内稿仅作结构化导读。
# powershell-sandbox - PowerShell 安全沙箱
**版本**: 0.1.0
**作者**: 小蒲萄 (Clawd)
**创建日期**: 2026-03-18
**平台**: Windows PowerShell 5.1+ / PowerShell 7+
---
## 📖 简介
在受限的 PowerShell 环境中安全执行用户脚本，提供：
- ✅ **超时控制** - 防止无限循环
- ✅ **命令白名单** - 只允许安全命令
- ✅ **输出限制** - 防止日志炸弹
- ✅ **安全检查** - 执行前扫描危险代码
- ✅ **审计日志** - 记录所有执行
- ✅ **文件隔离** - 限制在工作目录内
---
## 🚀 快速开始
### 基本用法
```powershell
# 执行脚本（默认 30 秒超时）
.\src\sandbox.ps1 -ScriptPath "C:\path\to\script.ps1"
# 自定义超时时间
.\src\sandbox.ps1 -ScriptPath "script.ps1" -TimeoutSeconds 60
# 指定工作目录
.\src\sandbox.ps1 -ScriptPath "script.ps1" -WorkingDirectory "C:\workspace"
# 允许网络访问（谨慎使用！）
.\src\sandbox.ps1 -ScriptPath "script.ps1" -AllowNetwork
```
### 在 OpenClaw 中使用
```powershell
# 通过 exec 调用
exec(
command: '.\skills\powershell-sandbox\src\sandbox.ps1 -ScriptPath "C:\Users\99236\.openclaw\workspace\scripts\user-script.ps1"',
timeout: 60
)
```
---
## ⚙️ 参数说明
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `-ScriptPath` | string | **必填** | 要执行的脚本路径 |
| `-TimeoutSeconds` | int | 30 | 执行超时时间（秒） |
| `-MaxOutputLines` | int | 1000 | 最大输出行数 |
| `-MaxOutputChars` | int | 50000 | 最大输出字符数 |
| `-WorkingDirectory` | string | 脚本目录 | 工作目录 |
| `-AllowNetwork` | switch | $false | 允许网络访问（⚠️ 高风险） |
| `-AllowedCommands` | string[] | 内置白名单 | 自定义允许的命令 |
---
## 🔒 安全特性
### 1. 命令白名单
**允许的命令**（部分）：
- 基础输出：`Write-Host`, `Write-Output`, `Write-Warning`
- 文件操作：`Get-Content`, `Set-Content`, `Get-ChildItem`, `Test-Path`
- 路径操作：`Join-Path`, `Split-Path`, `Resolve-Path`
- 数据处理：`Select-Object`, `Where-Object`, `ForEach-Object`, `Sort-Object`
- 格式转换：`ConvertTo-Json`, `ConvertFrom-Json`, `ConvertTo-Csv`
- 日期时间：`Get-Date`, `Get-TimeSpan`, `Start-Sleep`
**禁止的命令**：
- ❌ 网络访问：`Invoke-WebRequest`, `Invoke-RestMethod`, `Start-BitsTransfer`
- ❌ 进程管理：`Start-Process`, `Invoke-Expression`, `Get-Process`
- ❌ 远程执行：`Enter-PSSession`, `Invoke-Command`, `New-PSSession`
- ❌ 注册表：`Get-ItemProperty -Path HKLM:*`
- ❌ 服务管理：`Get-Service`, `Start-Service`, `Stop-Service`
- ❌ 计划任务：`Get-ScheduledTask`, `Register-ScheduledTask`
- ❌ WMI/CIM：`Get-WmiObject`, `Get-CimInstance`
- ❌ 代码执行：`Invoke-Expression`, `Add-Type`, `IEX`
### 2. .NET 类型限制
**允许的类型**：
- `System.String`, `System.Int32`, `System.DateTime`
- `System.IO.Path`, `System.IO.File`, `System.IO.Directory`
- `System.Math`, `System.Convert`, `System.Guid`
- `System.Text.StringBuilder`, `System.Text.RegularExpressions.Regex`
**禁止的类型**：
- ❌ `System.Net.*`（网络）
- ❌ `System.Diagnostics.Process`（进程）
- ❌ `System.Reflection.*`（反射）
- ❌ `System.Management.Automation.*`（PowerShell 内部）
- ❌ `System.ServiceProcess.*`（服务）
- ❌ `System.Threading.*`（线程）
### 3. 执行前安全检查
沙箱会在执行前扫描脚本内容，检测：
- 禁止的命令调用
- 禁止的 .NET 类型
- URL（可能尝试网络访问）
- `IEX` 缩写（Invoke-Expression）
发现违规会立即拒绝执行并报告具体问题。
### 4. 超时保护
使用 PowerShell Job 机制，超时后自动终止：
```powershell
$job = Start-Job -ScriptBlock $script
$completed = Wait-Job -Job $job -Timeout $TimeoutSeconds
if (-not $completed) {
Stop-Job -Job $job
Write-Error "执行超时！"
}
```
### 5. 输出限制
- 最大行数：1000 行（可配置）
- 最大字符数：50000 字符（可配置）
- 超出部分自动截断并提示
### 6. 文件路径隔离
脚本只能访问工作目录内的文件，防止遍历到系统目录。
---
## 📋 退出代码
| 代码 | 含义 |
|------|------|
| 0 | 执行成功 |
| 1 | 脚本文件不存在 |
| 2 | 安全检查失败 |
| 3 | 脚本执行错误 |
| 4 | 执行超时 |
---
## 🧪 测试用例
### 测试 1：安全脚本执行
```powershell
# test-safe.ps1
Write-Host "Hello from sandbox!"
$numbers = 1..10
$sum = ($numbers | Measure-Object -Sum).Sum
Write-Host "Sum of 1-10: $sum"
```
执行：
```powershell
.\src\sandbox.ps1 -ScriptPath "test-safe.ps1"
```
预期输出：
```
[2026-03-18 09:15:00] [INFO] 开始沙箱执行
[2026-03-18 09:15:00] [INFO] 安全检查通过 ✓
[2026-03-18 09:15:01] [INFO] 执行完成
========== 执行输出 ==========
Hello from sandbox!
Sum of 1-10: 55
========== 执行统计 ==========
状态：成功
行数：2
字符数：38
```
### 测试 2：危险命令拦截
```powershell
# test-dangerous.ps1
Invoke-WebRequest -Uri "https://example.com"
```
执行：
```powershell
.\src\sandbox.ps1 -ScriptPath "test-dangerous.ps1"
```
预期输出：
```
[2026-03-18 09:15:00] [INFO] 执行安全检查...
[2026-03-18 09:15:00] [ERROR] 安全检查失败！
[2026-03-18 09:15:00] [ERROR] - 包含禁止命令：Invoke-WebRequest
```
### 测试 3：超时保护
```powershell
# test-timeout.ps1
Write-Host "Starting..."
Start-Sleep -Seconds 60
Write-Host "Done!"
```
执行（30 秒超时）：
```powershell
.\src\sandbox.ps1 -ScriptPath "test-timeout.ps1" -TimeoutSeconds 30
```
预期输出：
```
[2026-03-18 09:15:00] [INFO] 等待脚本执行（超时：30 秒）...
[2026-03-18 09:15:30] [ERROR] 超时！强制终止执行...
```
### 测试 4：文件操作（工作目录内）
```powershell
# test-file.ps1
$content = Get-Content "data.txt"
Write-Host "File content: $content"
Set-Content "output.txt" "Processed: $content"
```
执行：
```powershell
.\src\sandbox.ps1 -ScriptPath "test-file.ps1" -WorkingDirectory "C:\workspace"
```
---
## 📁 文件结构
```
skills/powershell-sandbox/
├── SKILL.md # 技能文档（本文件）
├── src/
│ ├── sandbox.ps1 # 沙箱执行器（核心）
│ ├── test-safe.ps1 # 测试用例 - 安全脚本
│ ├── test-dangerous.ps1 # 测试用例 - 危险脚本
│ └── test-timeout.ps1 # 测试用例 - 超时脚本
└── README.md # 使用说明（可选）
```
---
## 🔧 自定义配置
### 扩展命令白名单
编辑 `sandbox.ps1` 中的 `$DEFAULT_ALLOWED_COMMANDS` 数组：
```powershell
$DEFAULT_ALLOWED_COMMANDS = @(
# ... 现有命令 ...
"Your-Safe-Cmdlet" # 添加新命令
)
```
### 调整安全级别
**更严格**（推荐用于不受信任的脚本）：
```powershell
.\src\sandbox.ps1 -ScriptPath "script.ps1" `
-TimeoutSeconds 10 `
-MaxOutputLines 100 `
-MaxOutputChars 5000
```
**更宽松**（仅用于可信脚本）：
```powershell
.\src\sandbox.ps1 -ScriptPath "script.ps1" `
-TimeoutSeconds 300 `
-AllowNetwork
```
---
## 📊 使用场景
### ✅ 适合的场景
- 执行用户提交的数据处理脚本
- 运行自动化任务（文件整理、日志分析）
- 测试 PowerShell 代码片段
- 教学/演示环境
- 需要隔离的批处理任务
### ❌ 不适合的场景
- 需要访问网络的脚本（使用 `-AllowNetwork` 需谨慎）
- 需要调用外部程序的脚本
- 需要管理员权限的操作
- 长时间运行的任务（>5 分钟）
- 需要交互式输入的脚本
---
## 🛡️ 安全建议
1. **始终使用沙箱** - 即使脚本来自可信来源
2. **设置合理超时** - 根据任务复杂度调整
3. **限制输出大小** - 防止日志炸弹
4. **审计所有执行** - 记录到 `.learnings/sandbox-log.md`
5. **定期更新白名单** - 根据实际需求调整
6. **不要在外部接口使用** - Feishu/Telegram/WhatsApp 中拒绝执行
---
## 📝 更新日志
### v0.1.0 (2026-03-18)
- ✅ 初始版本发布
- ✅ 命令白名单/黑名单机制
- ✅ .NET 类型限制
- ✅ 执行前安全检查
- ✅ 超时保护（Job 机制）
- ✅ 输出限制
- ✅ 审计日志
- ✅ 退出代码规范
---
## 🤝 贡献
欢迎提交 Issue 和 PR 来改进沙箱的安全性和功能！
**安全报告**：如发现安全漏洞，请优先通过私密渠道报告。
---
## 📄 许可证
MIT License
---
*最后更新：2026-03-18*