ZeroClaw Python Skills 执行指南：三层安全策略、可信本机运行与自定义 Docker 运行时镜像

• 人工智能
• AI Agent
• 交互助手
• 工具调用
• MCP Clients
• 本地部署
• Agent 工作流
• RAG

ZeroClaw 可以直接运行 Python skills，但现实的 Python 工作负载通常需要在两种显式部署选择中二选一：在可信主机 Python 环境中运行，或放进一个预先装好 Python 与依赖包的自定义 Docker 运行时镜像。默认配置刻意保持保守，会拦截大量"复制粘贴式"的 Python 用法，直到你明确选定信任边界。读完本文，你将掌握 ZeroClaw 的 skill 审计、shell 策略、执行边界三层机制，能配置[risk_profiles]与[runtime]让 Python 脚本以本机或容器化方式安全运行，并理解工作区挂载的 fail-closed 校验原理。

Python skill 执行的入口：内置 shell 工具

ZeroClaw 中的 Python 脚本通过内置 shell 工具（shelltool）调用。这一点需要特别注意：如果某个SKILL.toml自行声明了[[tools]]条目且kind = "shell"或kind = "script"，该 skill 工具当前是按 shell 策略以宿主子进程方式执行，而不会走runtime.kind = "docker"容器化路径。因此，若要实现容器化 Python 执行，目前有两种做法：

• 在 skill 的指令中，让模型通过内置 shell 工具调用 Python 脚本；
• 让 skill 工具的命令显式进入你想要的容器边界。

这一点在 python-skills.md 中有明确说明，配置实现可对照 crates/zeroclaw-config/src/schema.rs。

三层安全体系：skill 审计、shell 策略、执行边界

Python skill 的执行被三个彼此独立的层控制，缺一不可：

第一层：Skill 审计（[skills].allow_scripts）

技能加载配置定义在 schema.rs 的SkillsConfig：

[skills] open_skills_enabled = false # 社区 open-skills 仓库默认关闭，显式开启 allow_scripts = false # shell 类脚本文件默认禁止（secure by default） prompt_injection_mode = "full"

关键结论（也是很多人容易搞反的一点）：Python 辅助文件（.py）并不要求allow_scripts = true。审计实现见 crates/zeroclaw-runtime/src/skills/audit.rs：

• SkillAuditOptions { allow_scripts: bool }控制的是"类脚本文件"（is_unsupported_script_file，即.sh、.bash、.ps1及 shebang shell 文件）的加载；
• 当allow_scripts = false时，这类文件会被记录为scripts_blocked并进入审计报告 findings；
• 而带#!/usr/bin/env python3shebang 的.py文件在审计中属于可接受范围，其测试用例audit_allows_python_shebang_file_when_early_text_contains_sh直接验证了这一行为。

只有在已人工审查过 skill 源码的前提下，才应开启allow_scripts = true；同时必须在风险 profile 的allowed_commands中允许解释器（python、python3、pip）。

第二层：Shell 策略（allowed_commands严格白名单）

风险 profile 定义在 schema.rs 的RiskProfileConfig。allowed_commands在非空时是严格的可执行文件白名单——不在名单里的可执行文件一律无法通过 shell 工具启动；在此基础上，shell 策略还会继续检查破坏性模式与解释器参数风险。

从 crates/zeroclaw-runtime/src/tools/shell.rs 可以看到执行前的完整校验链路：

1. security.validate_command_execution_for_shell(command, approved, shell_dialect)：先过白名单与风险评级；
2. forbidden_workspace_path_argument_for_shell(...)：再做方言感知的禁止路径参数扫描（防止符号链接逃逸）；
3. runtime.build_shell_command(...)：由RuntimeAdapter按当前运行时构造真实命令；
4. sandbox.wrap_command(...)：如果启用了沙箱，在此处包裹命令；
5. cmd.env_clear()：清空环境变量后再重建，避免把 API Key 等机密泄漏给子进程（对应 CWE-200），只回填SAFE_SHELL_ENV_VARS白名单变量与 profile 中配置的shell_env_passthrough。

此外 shell 工具还有 1MB 输出截断（MAX_OUTPUT_BYTES = 1_048_576）与超时强杀（ChildGroupGuard对进程组 SIGKILL）等防护。

第三层：执行边界（sandbox_*与[runtime]）

被允许的命令在何处执行、受到什么资源约束，由风险 profile 的sandbox_enabled/sandbox_backend（如firejail、landlock、docker）与全局[runtime]段共同决定。默认风险 profile 是level = "supervised"、workspace_only = true、block_high_risk_commands = true，即默认禁止高风险命令。

被默认拦截的 Python 用法

ZeroClaw 刻意阻止"内联解释器执行"，因为这些写法等于把 shell 命令字符串变成一个任意代码容器，无法被审计：

python3 -c 'print("hello")' # 内联代码，无审计痕迹 python3 -m http.server # 裸起网络服务 python3 -m pip install requests # 运行时安装依赖 node -e 'console.log(process.env)' # 同类的解释器 -e 内联

对 Python skill 的正确姿势是：把代码放进可审计的脚本文件，再运行该文件：

python3 skills/portfolio/run.py

这样可执行文件本身会经过 skill 审计路径检查，也避免了把任意代码塞进 shell 命令字符串。环境变量前缀（如PYTHONPATH=... python3 script.py）同样属于策略敏感写法；需要稳定的运行时环境时，优先使用 wrapper 脚本、项目级虚拟环境，或把配置显式写进脚本内部。

模式 A：可信本机原生 Python（Trusted Native Python）

当 skill 可信、且希望直接使用宿主机的 Python 安装、已装包、文件系统权限与网络时，选用本机原生执行。适用场景：本地开发、单用户工作站、或你自己编写 skill 的家庭实验环境。

[runtime] kind = "native" # 默认值，直接调用宿主 shell shell = "sh" # 可选，指定 shell（bash、/bin/zsh、pwsh 等）

需要明确的代价：该模式移除了该 profile 下工具运行的 OS 级沙箱，剩余防线只剩普通用户权限与 ZeroClaw 策略检查。因此不要用它运行未经审核的第三方 skill，也不要用于多租户部署。

模式 B：自定义 Docker 运行时镜像（Custom Docker Runtime Image）

当希望 Python 依赖以可复现的容器镜像形式存在、且仍想给内置 shell 执行加一层运行时边界时，使用 Docker 运行时。

1. 构建带依赖的镜像

# Dockerfile.skill-exec FROM python:3.12-slim RUN pip install --no-cache-dir \ pandas \ polars \ requests WORKDIR /workspace

构建：

docker build -f Dockerfile.skill-exec -t zeroclaw-python-skills:local .

2. 指向镜像并启用 Docker 运行时

[runtime] kind = "docker" [runtime.docker] image = "zeroclaw-python-skills:local" network = "none" # 按需改为 "bridge" 等 memory_limit_mb = 512 cpu_limit = 1.0 read_only_rootfs = true mount_workspace = true allowed_workspace_roots = []

配置结构对应 schema.rs 的RuntimeConfig/DockerRuntimeConfig，默认值如下（与 crates/zeroclaw-config/fixtures/v1.toml 中的示例一致）：

kind = "docker"时，内置 shell 调用在临时容器中执行。Docker 构建命令的底层实现在 crates/zeroclaw-config/src/platform/docker.rs：docker run --rm --init --interactive，并按配置附加--network、--memory、--cpus、--read-only、--env与工作区挂载。

3. 避免嵌套沙箱：sandbox_backend = "none"

在 Docker 运行时模式下，应设置sandbox_backend = "none"，避免把 Docker 运行时再包进第二个独立沙箱容器。此时 Docker 运行时本身就是内置 shell 调用的执行边界，容器镜像与资源限制统一在runtime.docker中配置。

这一行为有集成测试背书：docker_runtime_no_nested_sandbox_9231.rs 验证了当runtime.kind = "docker"时，即使 profile 里写sandbox_backend = "docker"，最终posture.active_backend也会归一为"docker-runtime"，组装出的命令只包含一次docker run，不会出现嵌套 Docker 或镜像被沙箱默认镜像遮蔽的情况。

4. 网络与根文件系统的按需放宽

• 若 skill 需要出站 HTTP，刻意修改runtime.docker.network（如"bridge"）；
• 若 skill 需要写包缓存、报告或挂载工作区之外的临时状态，先评估是否应改写到/workspace下；确实不够时，才放宽read_only_rootfs。

原则是：默认拒绝，逐项、有意识地放开。

工作区挂载与 fail-closed 校验

当runtime.docker.mount_workspace = true时，ZeroClaw 将配置的工作区挂载到容器的/workspace并把它设为容器工作目录。skill 脚本应尽量使用工作区相对路径。

若需要进一步约束工作区路径，配置allowed_workspace_roots。ZeroClaw 在添加 Docker 卷挂载之前，会先对宿主工作区路径做校验，该校验fail-closed（默认拒绝）：

• 即使白名单为空，工作区也必须存在并能解析为规范路径（canonicalize）；
• 每个配置的白名单根目录也必须存在且能规范化；
• 只要有一条过期/无效的白名单条目，整个命令就会在 Docker 启动前被拒绝——即使另有条目匹配。

对应实现在 crates/zeroclaw-config/src/platform/docker.rs 的workspace_mount_path：工作区需为绝对路径、禁止挂载文件系统根/、每个allowed_workspace_roots都先canonicalize再逐一比对。shell 工具测试shell_reports_invalid_docker_workspace_root也验证了"白名单中存在无法规范化的目录 → 命令被拒绝"的行为。因此升级前务必清理过期条目或提前建好目标目录。

如何选择模式

• 可信本机原生 Python：你编写或已审核过这些 skill，且在单用户宿主机上追求最低延迟；
• 自定义 Docker 运行时镜像：需要可复现的依赖、生产级打包，或希望为内置 shell 调用提供显式容器边界；
• 更严格的风险 profile + 更窄的命令白名单 + 容器化执行：用于未经审核或多人共用的 skill 来源。

依赖安装建议放在镜像构建期、经过审核的本地虚拟环境，或其他 agent 轮次之外的搭建步骤；只有当你有意让运行时安装包成为该部署的一部分时，才把pip加入可信 profile 的allowed_commands。

延伸阅读

• Skills（skill 体系总览）
• Autonomy levels（自主级别与审批策略）
• Sandboxing（沙箱后端详解）
• Docker & containers（容器化部署）

• 人工智能
• AI Agent
• 交互助手
• 工具调用
• MCP Clients
• 本地部署
• Agent 工作流
• RAG