Unraidclaw

Complete Unraid server management via the UnraidCLaW REST API. Covers: - Docker containers (create/start/stop/remove/logs) - VMs (start/stop/restart/pause) -...

Security Scan

The skill's code and instructions match its stated Unraid management purpose, but the package metadata omits required credentials and the runtime scripts perform actions (reading a .env, printing request bodies, and disabling TLS verification) that are disproportionate or surprising compared to the declared requirements.

Purpose & Capability

The SKILL.md and included scripts clearly implement UnraidCLaW REST API operations (containers, VMs, array, etc.), which aligns with the name/description. However the registry metadata lists no required environment variables or credentials while both SKILL.md and every script expect an API key (UNRAIDCLAW_TOKEN) and an UNRAID_HOST — a clear mismatch. The included opencode_install.sh (creates a container from ghcr.io) is related to Unraid management but is an extra convenience action that should have been declared.

Instruction Scope

The runtime instructions and scripts instruct the agent to use curl -k (disables TLS validation) to talk to on-prem Unraid and repeatedly require an API token. The scripts source an environment file by default (../../.env), which may read unrelated local credentials, and they echo full request bodies to stdout (possible exposure of env values). The instructions do not ask to exfiltrate secrets, but they do give the agent broad discretion to read a .env and to print request payloads containing secrets.

Install Mechanism

No install spec is provided (instruction-only), and included scripts do not download arbitrary code from unknown URLs; they use the Unraid API to create containers which causes Unraid to pull images (e.g., ghcr.io). There are no high-risk external download URLs or archive extractions performed by the skill itself.

Credentials

The registry metadata declares no required env vars or primary credential, but the scripts and SKILL.md require UNRAIDCLAW_TOKEN and optionally UNRAID_HOST. The script's support for sourcing ../../.env increases the chance of accidentally exposing other local secrets. The skill also prints request bodies which may include sensitive values, so the requested/used environment access is not properly declared nor proportioned.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide agent settings. It is user-invocable and can be invoked autonomously (platform default) but there is no evidence it requests elevated persistent privileges beyond its own scripts.

What to consider before installing

This skill appears to implement Unraid API functionality, but there are important inconsistencies and privacy risks you should consider before installing: - The package metadata fails to declare required credentials. The scripts and SKILL.md require an API key (UNRAIDCLAW_TOKEN) and an UNRAID_HOST — the registry should have declared these. Treat this as a red flag and ask the author to update metadata. - The scripts by default source a ../../.env file. That can cause the skill to read arbitrary local environment variables (other API keys, passwords). If you use a shared or system-level .env, move sensitive data or avoid using this skill until it's fixed. - The code uses curl -k (disables TLS verification) to accept self-signed certs. Prefer installing the plugin's CA or enabling valid certs rather than disabling verification, especially if you expose Unraid beyond a trusted LAN. - The scripts echo request bodies and other diagnostic output. That can leak secrets to logs/console. Review the scripts and remove or sanitize such echoes before running in a production environment. - The opencode_install.sh creates a container pulled from ghcr.io and instructs you to configure an LLM provider key inside that container — review that container image and understand what credentials you will place into it. Recommended actions: 1) Ask the skill author to update registry metadata to list required env vars (UNRAIDCLAW_TOKEN, UNRAID_HOST) and explain any additional behaviors (reading .env). 2) Inspect and/or run the scripts in a safe test environment first. 3) Avoid keeping sensitive site-wide .env files at the default ../../.env path while testing. 4) Prefer not to use -k: add the Unraid certificate to your trust store or use a valid cert. 5) If you proceed, provide only a narrowly-scoped API key with minimal permissions needed and monitor logs for unexpected behavior.

UnraidCLaW 全套操作指南

API 基础

• Base URL: https://<UNRAID_IP>:9876
• 认证: x-api-key: <API_KEY> (Header)
• 返回格式: 统一包络 { "ok": true, "data": {...} } 或 { "ok": false, "error": {...} }
• TLS: 默认自签名证书，请求时加 -k 或在业务系统中关闭证书验证

版本检查（每次操作前必读）

当前测试版本: v0.1.27

每次执行 UnraidCLaW 操作前，先检查插件版本：

curl -s -k -H "x-api-key: $TOKEN" https://<UNRAID_IP>:9876/api/health
# 返回: {"ok":true,"data":{"status":"ok","version":"0.1.27","uptime":...}}

如果版本低于当前测试版本：

• 提醒用户："检测到 UnraidCLaW 版本为 X.X.X，最新版本为 0.1.27，建议升级以获得更好的兼容性"
• 升级方式：在 Unraid 社区应用里搜索 "UnraidClaw" 更新，或手动下载最新 txz 包

如果版本高于 0.1.27：

• 说明：技能描述基于 0.1.27，如遇 API 差异请告知

已知版本历史:

• 0.1.27 — 当前测试版本
• 0.1.21 — 历史安装包（仍存在于磁盘）

API 端点总表

分类	方法	端点	权限
Health	GET	/api/health	无
Docker	GET	/api/docker/containers	docker:read
Docker	GET	/api/docker/containers/:id	docker:read
Docker	GET	/api/docker/containers/:id/logs	docker:read
Docker	POST	/api/docker/containers	docker:create
Docker	POST	/api/docker/containers/:id/:action	docker:update
Docker	DELETE	/api/docker/containers/:id	docker:delete
VMs	GET	/api/vms	vms:read
VMs	GET	/api/vms/:id	vms:read
VMs	POST	/api/vms/:id/:action	vms:update
VMs	DELETE	/api/vms/:id	vms:delete
Array	GET	/api/array/status	array:read
Array	GET	/api/array/parity/status	array:read
Array	POST	/api/array/start	array:update
Array	POST	/api/array/stop	array:update
Array	POST	/api/array/parity/start	array:update
Array	POST	/api/array/parity/pause	array:update
Array	POST	/api/array/parity/resume	array:update
Array	POST	/api/array/parity/cancel	array:update
Disks	GET	/api/disks	disk:read
Disks	GET	/api/disks/:id	disk:read
Shares	GET	/api/shares	share:read
Shares	GET	/api/shares/:name	share:read
Shares	PATCH	/api/shares/:name	share:update
System	GET	/api/system/info	info:read
System	GET	/api/system/metrics	info:read
System	GET	/api/system/services	services:read
System	POST	/api/system/reboot	os:update
System	POST	/api/system/shutdown	os:update
Notifications	GET	/api/notifications	notification:read
Notifications	GET	/api/notifications/overview	notification:read
Notifications	POST	/api/notifications	notification:create
Notifications	POST	/api/notifications/:id/archive	notification:update
Notifications	DELETE	/api/notifications/:id	notification:delete
Network	GET	/api/network	network:read
Users	GET	/api/users/me	me:read
Logs	GET	/api/logs/syslog	logs:read

权限矩阵

分类	权限
Docker	docker:read, docker:create, docker:update, docker:delete
VMs	vms:read, vms:update, vms:delete
阵列/存储	array:read, array:update, disk:read, share:read, share:update
系统	info:read, os:update, services:read
通知	notification:read, notification:create, notification:update, notification:delete
网络	network:read
用户	me:read
日志	logs:read

预设角色：Read Only、Docker Manager、VM Manager、Full Admin、None

核心操作详解

1. 容器列表

curl -s -k -H "x-api-key: $UNRAIDCLAW_TOKEN" \
  https://192.168.8.11:9876/api/docker/containers | python3 -m json.tool

2. 创建容器（POST /api/docker/containers）

Body 参数（仅 image 必填）：

{
  "image": "ghcr.io/anomalyco/opencode:latest",
  "name": "opencode",
  "ports": ["4096:4096", "4097:4097"],
  "volumes": [
    "/mnt/user/appdata/opencode/config:/home/opencode/.config/opencode",
    "/mnt/user/appdata/opencode/data:/home/opencode/.local/share/opencode"
  ],
  "env": [
    "HTTP_PROXY=http://192.168.8.30:7893",
    "HTTPS_PROXY=http://192.168.8.30:7893",
    "NO_PROXY=localhost,127.0.0.1",
    "ENABLE_WEB_UI=true",
    "PUID=99",
    "PGID=100"
  ],
  "restart": "unless-stopped",
  "network": "bridge",
  "icon": "https://example.com/icon.png",
  "webui": "http://[IP]:4097/"
}

注意：

• 容器创建后会自动生成 DockerMan XML 模板，出现在 Unraid Docker 页面
• volumes 格式：宿主机路径:容器内路径
• env 格式：KEY=value
• ports 格式：宿主机端口:容器端口

3. 容器操作（POST /api/docker/containers/:id/:action）

# 启动
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/docker/containers/opencode/start

# 停止
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/docker/containers/opencode/stop

# 重启
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/docker/containers/opencode/restart

# 暂停
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/docker/containers/opencode/pause

# 取消暂停
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/docker/containers/opencode/unpause

4. 查看容器日志

curl -s -k -H "x-api-key: $TOKEN" \
  "https://HOST/api/docker/containers/opencode/logs?stdout=1&stderr=1&tail=50"

5. 删除容器

curl -s -k -X DELETE -H "x-api-key: $TOKEN" \
  https://HOST/api/docker/containers/opencode

6. 阵列操作

# 查看阵列状态
curl -s -k -H "x-api-key: $TOKEN" \
  https://HOST/api/array/status

# 启动阵列
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/array/start

# 停止阵列
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/array/stop

7. 系统操作

# 重启 Unraid 宿主机
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/system/reboot

# 关机
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  https://HOST/api/system/shutdown

8. VM 操作

# 列表
curl -s -k -H "x-api-key: $TOKEN" \
  https://HOST/api/vms

# 启动/停止/重启/强制停止
curl -s -k -X POST -H "x-api-key: $TOKEN" \
  "https://HOST/api/vms/<vm_id>/start"

curl -s -k -X POST -H "x-api-key: $TOKEN" \
  "https://HOST/api/vms/<vm_id>/stop"

9. 创建通知

curl -s -k -X POST -H "x-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  https://HOST/api/notifications \
  -d '{
    "title": "容器已停止",
    "body": "OpenCode 容器在 19:55 异常停止",
    "severity": "warning"
  }'

镜像访问代理配置（国内必读）

国内服务器访问 ghcr.io（GitHub Container Registry）通常需要代理。在创建容器时通过 env 传入：

"env": [
  "HTTP_PROXY=http://192.168.8.30:7893",
  "HTTPS_PROXY=http://192.168.8.30:7893",
  "NO_PROXY=localhost,127.0.0.1,192.168.0.0/16"
]

但注意：

• 代理环境变量作用于容器内进程，如果镜像拉取在 Docker daemon 层发生（如使用代理registry），需要在 Unraid Docker 设置里配置 registry mirror
• 容器运行时的 HTTP_PROXY/HTTPS_PROXY 影响容器内所有出站请求

常见错误处理

错误码	含义	解决方案
GRAPHQL_ERROR / Invalid CSRF token	API Key 权限不足或格式错误	检查 Key 是否有对应操作权限
DOCKER_CREATE_FAILED / Conflict	容器名已占用	先删除同名容器
DOCKER_CREATE_FAILED / No such image	镜像在主机上不存在	手动 docker pull 或配置代理
DOCKER_CREATE_FAILED / network not found	网络不存在	检查 network 字段，用 bridge
NOT_FOUND	端点或资源不存在	检查 URL 和容器/VM ID

脚本工具

配套脚本在 scripts/ 目录：

• unraid_docker.sh — Docker 容器常用操作（创建/启动/停止/删除/日志）
• unraid_common.sh — 公共函数（API 调用/凭据读取）
• opencode_install.sh — OpenCode Docker 容器一键安装（带代理）

使用前先设置环境变量或在 .env 文件中配置：

export UNRAIDCLAW_TOKEN="your-api-key-here"
export UNRAID_HOST="192.168.8.11"

参考文档

• UnraidCLaW GitHub: https://github.com/emaspa/unraidclaw
• API 完整源码: packages/unraid-plugin/server
• OpenClaw Plugin: packages/openclaw-plugin（以 npm 包 unraidclaw 发布）