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

人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载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_scriptsshell 类辅助文件.sh、.bash、.ps1、shebang shell 文件能否从 skill 包中加载Python.py辅助文件默认允许Shell 策略[risk_profiles.alias].allowed_commandsshell 工具能否调用python、python3、pip或其他可执行文件执行边界[risk_profiles.alias].sandbox_*与[runtime]被允许的命令实际在哪里运行以及应用哪些文件系统、网络、资源限制第一层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.rsSkillAuditOptions { 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 可以看到执行前的完整校验链路security.validate_command_execution_for_shell(command, approved, shell_dialect)先过白名单与风险评级forbidden_workspace_path_argument_for_shell(...)再做方言感知的禁止路径参数扫描防止符号链接逃逸runtime.build_shell_command(...)由RuntimeAdapter按当前运行时构造真实命令sandbox.wrap_command(...)如果启用了沙箱在此处包裹命令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可信本机原生 PythonTrusted Native Python当 skill 可信、且希望直接使用宿主机的 Python 安装、已装包、文件系统权限与网络时选用本机原生执行。适用场景本地开发、单用户工作站、或你自己编写 skill 的家庭实验环境。[runtime] kind native # 默认值直接调用宿主 shell shell sh # 可选指定 shellbash、/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 中的示例一致字段默认值说明runtime.kindnativenative/docker/cloudflareruntime.docker.imagealpine:3.20执行 shell 命令所用的镜像runtime.docker.networknoneDocker 网络模式none、bridge等runtime.docker.memory_limit_mb512内存上限MB0/缺省表示不显式限制runtime.docker.cpu_limit1.0CPU 上限0 表示不限制runtime.docker.read_only_rootfstrue只读根文件系统runtime.docker.mount_workspacetrue将工作区挂载到容器/workspaceruntime.docker.allowed_workspace_roots[]工作区根目录白名单fail-closed 校验kind docker时内置 shell 调用在临时容器中执行。Docker 构建命令的底层实现在 crates/zeroclaw-config/src/platform/docker.rsdocker 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。延伸阅读Skillsskill 体系总览Autonomy levels自主级别与审批策略Sandboxing沙箱后端详解Docker containers容器化部署赞分享人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载相关推荐Docker安全实战从镜像到运行时的全方位防护策略Docker安全实战从镜像到运行时的全方位防护策略 终极防护指南保护你的Docker环境免受安全威胁 在当今云原生时代Docker已成为应用部署的云原生容器运行时虚拟化容器编排AutoAgent 自定义 Docker 沙箱完全指南从定制镜像构建到运行时配置AutoAgent 自定义 Docker 沙箱完全指南从定制镜像构建到运行时配置 本指南以 AutoAgent 仓库内沿袭自 OpenHands 的自定义沙箱人工智能大模型AI AgentAgent 框架工具调用自主智能体RAGAutoAgent Docker 沙盒运行时深度解析架构原理、镜像标签体系与安全执行机制AutoAgent Docker 沙盒运行时深度解析架构原理、镜像标签体系与安全执行机制 本篇技术指南围绕 AutoAgent 开源仓库的运行时Runtim人工智能大模型AI AgentAgent 框架工具调用自主智能体RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考