OpenClaw技能开发实战：从SKILL.md到Docker沙箱

1. 项目概述为什么你需要亲手写一个 OpenClaw 技能OpenClaw 不是那种装完就能“自动变聪明”的黑箱工具。它更像一把刚出厂的瑞士军刀——出厂时配了49把基础刀片也就是内置技能能开瓶、剪线、拧螺丝社区在 ClawHub 上又贡献了几千个定制刀头从咖啡机定时器到 Git 分支清理器应有尽有。但真正让你每天多出两小时、让老板说“这事儿你办得真快”的从来不是别人造好的那把刀而是你根据手头那个正在写的季度汇报PPT、那个总卡在CI流水线第三步的测试脚本、或者那个要反复给法务部发的合同红头文件亲手磨出来的一小段刃口。我做 OpenClaw 技能开发三年经手过67个内部项目最深的体会是所有被高频使用的技能90%以上都诞生于某个周五下午三点当你第N次手动点开Jupyter、导出Word、再拖进微信发给编辑而对方回了一句“格式有点乱能重发个带目录的吗”的时候。那一刻你脑子里闪过的不是“我要学Python”而是“要是敲个/notebook-to-docx就能搞定该多好”。这篇教程不讲概念不画架构图不堆术语。它就干一件事带你从零写出两个真实可用、能立刻塞进你工作流里的技能。第一个把 Jupyter Notebook 一键转成结构完整、样式规范的 Word 文档——不是那种标题变加粗、代码变灰色的“能看就行”版而是连 Poppins 字体、Courier New 代码块、表格边框粗细、图片Alt文本都原样复刻的交付级输出。第二个调用 Nano Banana ProGemini 3 Pro Image模型生成专业示意图比如“用流程图展示Transformer的QKV计算过程”并确保它不会在API限流时擅自降级到免费版模型也不会把生成的图默默存进硬盘然后对你微笑说“已保存”。整个过程你会摸到 OpenClaw 的三个核心关节SKILL.md 这个“行为说明书”怎么写才让AI不瞎发挥Docker 沙箱怎么配才能既让技能安全调用你的 API Key又不让它一不小心rm -rf /了你的家目录最后怎么把本地跑通的技能变成一个别人在 Telegram 里敲/install nano-banana-pro就能用的公共包。这不是玩具项目的拼装而是生产环境里真实技能的全生命周期实操。接下来我们直接上手从创建第一个文件夹开始。2. 核心设计思路SKILL.md 不是配置文件是给AI的“操作手册”很多人第一次写 SKILL.md会下意识把它当成config.json或Dockerfile来对待——想着怎么“设置参数”怎么“定义接口”。这是最大的误区。OpenClaw 的技能机制本质是一场人与大模型之间的“任务委托协议”。你写的不是机器指令而是一份给一个非常聪明、但极度缺乏领域常识和上下文约束的助手看的操作手册。它的核心逻辑是你负责说清楚“做什么”和“不能做什么”AI 负责想“怎么做”。理解这一点是写出稳定、可靠技能的第一步。2.1 为什么不用 MCP 或传统插件直击效率痛点在动手前必须厘清一个关键问题既然已经有 MCPModel Context Protocol服务器这类成熟方案为什么 OpenClaw 要另起炉灶搞一套基于纯文本指令的技能系统答案藏在“启动成本”和“使用场景”的错位里。MCP 服务器比如你在 Claude Code 里用的那些工具本质上是一个独立运行的、有状态的后端服务。它需要你写一个完整的 HTTP 接口处理请求/响应、管理连接池、做错误重试、维护会话状态……这就像为了在家门口修一条小路先得建一个水泥厂、挖一个砂石矿、再培训一支施工队。它强大、稳定、适合长期运行的复杂集成比如一个需要实时监听 GitHub Webhook 并自动创建 Jira 子任务的系统。而 OpenClaw 的技能是为“一次性、单点、轻量级自动化”而生。它解决的是“我现在就想把这份 notebook 发给老板别让我再点十下鼠标”的即时需求。它的优势在于“零部署”你写完 SKILL.md 和一个 Python 脚本扔进~/.openclaw/skills/目录OpenClaw 的文件监视器约250ms内就会自动加载它。没有进程管理没有端口冲突没有依赖版本地狱。这背后的设计哲学是对于 80% 的日常自动化需求开发者的时间成本远高于服务器的资源成本。让你花五分钟写完一个技能比花两小时搭好一个 MCP 服务更能提升真实生产力。所以当你决定写一个 OpenClaw 技能时先问自己这个任务是“一次性的、明确的、边界清晰的”吗比如“把当前目录下的所有.py文件按行数排序并输出”、“从 Slack 历史记录里提取过去一周所有带urgent的消息”、“把 PR 描述里的#TODO列表自动同步到 Notion 数据库”。如果是那么 SKILL.md 就是你的最优解。它不是技术上的妥协而是对工作流本质的精准把握——把“思考如何自动化”这件事压缩到最小粒度。2.2 SKILL.md 的三层结构元数据、行为指南、硬性规则一个健壮的 SKILL.md 文件绝不是 YAML 前言加一段模糊的 Markdown。它必须包含三个逻辑严密、层层递进的部分每一部分都承担着不可替代的角色第一层YAML 前言Metadata—— 它是“准入许可证”这部分决定了技能能否被 OpenClaw “看见”和“信任”。name和description是它的身份证user-invocable: true是它的上岗证。而metadata.openclaw.requires则是它的健康证明和安全审查报告。requires.bins: [uv]不是可有可无的装饰它意味着“如果我的宿主机 PATH 里找不到uv这个二进制文件那就请直接跳过我不要尝试加载更不要等到执行时才报错。” 这种“失败前置”的设计极大提升了技能的鲁棒性。我见过太多技能因为依赖缺失在用户第一次调用时抛出一长串ModuleNotFoundError让用户误以为是 OpenClaw 本身坏了。而requires.env: [REPLICATE_API_TOKEN]则是另一道防火墙它确保敏感凭证在技能被加载的瞬间就被验证而不是在 API 调用失败后才提示“请检查你的 token”。第二层Markdown 主体Usage Features—— 它是“操作指南”这是给 AI 看的“怎么做”。这里的关键是具体、可执行、无歧义。uv run --with nbformat --with python-docx --with Pillow python {baseDir}/notebook_to_docx.py notebook_path [output_path]这条命令每一个字符都是精心设计的uv run --with ...明确指定了依赖的安装和隔离方式避免了pip install可能污染全局环境的风险{baseDir}是一个动态模板变量它让脚本路径与技能位置解耦保证了技能的可移植性notebook_path和[output_path]使用了标准的 Unix 风格占位符清晰地告诉 AI 哪里是必填参数哪里是可选参数。如果你在这里写“运行转换脚本”AI 就会去猜脚本叫什么、参数怎么传、路径在哪。而你写了一条完整的、可复制粘贴的命令AI 就只需要做一件事把notebook_path替换成用户实际提供的路径然后执行。这就是“降低认知负荷”的力量。第三层Rules规则—— 它是“法律红线”这是整个 SKILL.md 中最常被忽视、也最致命的部分。AI 的默认行为准则是“完成任务”而不是“按你的要求完成任务”。当 Nano Banana Pro 的 API 因为流量高峰返回503 Service Unavailable时一个没有 Rules 的技能会让 AI 自作主张地去尝试google/nano-banana非Pro版因为它认为“生成一张图”比“生成一张 Pro 版的图”更重要。而 Rules 就是给这个聪明的助手划下的绝对禁区“只许用google/nano-banana-pro绝不许 fallback只许把图发到聊天窗口绝不许只存到硬盘。” 这不是对 AI 的不信任而是对“任务目标”的终极确认。在生产环境中每一条 Rules 都是你和 AI 之间签订的 SLA服务等级协议。2.3 为什么选择 uv 而不是 pip一个关于依赖隔离的务实选择教程里反复出现uv run --with ...而不是大家更熟悉的pip install或python -m venv。这不是为了炫技而是基于一个残酷的现实Python 生态的依赖冲突是自动化脚本最大的隐形杀手。想象一下这个场景你的系统里已经用pip install安装了nbformat5.9.0用于日常开发。而你的 notebook-to-docx 脚本经过大量测试发现只有在nbformat5.7.3下才能完美处理某些老旧的.ipynb文件格式。如果你用pip install要么升级全局版本可能破坏你的其他项目要么创建一个全新的虚拟环境增加启动延迟和磁盘占用。而uv run --with nbformat5.7.3的威力在于它会在内存中构建一个极轻量的、仅包含指定版本依赖的执行环境执行完即焚对你的系统零影响。uv是 Rust 编写的 Python 包管理器其速度是pip的数十倍且其--with模式专为这种“一次性的、脚本级的依赖管理”而优化。它不修改你的site-packages不创建.venv目录只是在运行时为你提供一个干净的、受控的依赖沙盒。这与 OpenClaw 的 Docker 沙箱理念一脉相承——都是在不同层级上为每一次自动化任务提供一个“用完即走”的纯净空间。选择uv就是选择了“确定性”。在自动化领域确定性就是生产力。3. 实操详解从零构建 notebook-to-docx 技能现在我们放下所有理论进入真正的“手把手”环节。我会以一个资深开发者的视角带你走过每一个步骤不仅告诉你“怎么做”更会解释“为什么这么做”、“如果做错了会怎样”以及“我踩过的坑在哪里”。请打开你的终端我们开始。3.1 创建技能目录与基础文件结构首先我们需要为这个技能建立一个专属的“家”。在 OpenClaw 中技能的存放位置决定了它的作用域。~/.openclaw/skills/是全局技能目录里面放的技能对所有 OpenClaw 会话都可见而project/skills/是项目级目录只对当前项目生效。对于一个通用的、高频使用的技能我们首选全局目录。mkdir -p ~/.openclaw/skills/notebook-to-docx这条命令创建了一个名为notebook-to-docx的文件夹。注意文件夹名将直接成为 slash 命令的名字/notebook-to-docx所以请确保它简洁、无空格、符合 Unix 命名习惯小写字母、连字符分隔。接下来我们要创建这个技能的“灵魂”——SKILL.md文件。它必须严格位于技能文件夹的根目录下且文件名大小写完全匹配。touch ~/.openclaw/skills/notebook-to-docx/SKILL.md现在用你最喜欢的编辑器VS Code, Vim, Nano打开这个空文件。我们将从 YAML 前言开始编写。重要提示YAML 对缩进极其敏感且不支持多行字符串。所以metadata字段必须写成一行 JSON而不是嵌套的 YAML。这是新手最容易犯错的地方会导致 OpenClaw 完全无法解析该技能。--- name: notebook-to-docx description: Convert Jupyter notebooks to Word documents with proper formatting user-invocable: true metadata: {openclaw: {requires: {bins: [uv]}}} ---让我们逐行解读name: notebook-to-docx: 这是技能的唯一标识符也是 Telegram 中的 slash 命令。它必须与文件夹名一致。description: ...: 这句话至关重要。OpenClaw 的 Agent 在决定“是否调用这个技能”时会将这句话与用户的当前输入例如/notebook-to-docx后面跟的文本进行语义匹配。所以描述要精准要包含核心动词Convert和核心对象Jupyter notebooks, Word documents。user-invocable: true: 这个开关决定了技能是否注册为 Telegram 的 slash 命令。设为false它就只能被 Agent 在后台自动调用用户无法手动触发。metadata: 这里我们只加了一个最基础的依赖检查bins: [uv]。这意味着如果uv不在你的系统 PATH 中OpenClaw 会在加载阶段就静默跳过这个技能而不会等到你执行/notebook-to-docx时才报错。这是一种优雅的失败处理。提示如果你希望这个技能只在你明确输入/notebook-to-docx时才触发而禁止 Agent 在后台自动调用比如当用户说“帮我把这份笔记转成 Word”时你需要添加disable-model-invocation: true。这是一个非常实用的安全开关能防止 AI 在你不期望的时候“自作主张”。3.2 编写 SKILL.md 主体让 AI 知道“怎么做”YAML 前言之后就是 Markdown 主体。这里是我们向 AI 传达“操作指南”的地方。请将以下内容严格按顺序、一字不差地粘贴到SKILL.md文件中放在---分隔符的下方。# Notebook to DOCX Converter Converts Jupyter notebooks (.ipynb) to Word documents (.docx) with proper formatting. ## Usage Run the conversion script: uv run --with nbformat --with python-docx --with Pillow python {baseDir}/notebook_to_docx.py notebook_path [output_path] If output_path is not specified, creates a .docx file with the same name as the notebook. ## Features - Markdown formatting preserved as Word styles (bold, italics, headings) - Backticks preserved around inline code with monospace font - Code blocks show triple backticks and language name, use Courier New font - Non-code text uses Poppins font - Images embedded with alt text - Hyperlinks preserved and clickable - Markdown tables converted to Word tables ## Requirements - nbformat - python-docx - Pillow这段内容的设计处处体现着“降低 AI 认知负荷”的原则标题层级清晰#是技能总览##是核心操作###虽然这里没用但你可以加可以是子功能。AI 会据此理解文档结构。Usage 部分是一条“可执行命令”它不是一个描述而是一个可以直接运行的 shell 命令。notebook_path和[output_path]是标准的占位符AI 会准确地将用户输入替换进去。{baseDir}是 OpenClaw 提供的魔法变量它会在运行时自动替换为~/.openclaw/skills/notebook-to-docx/这个路径这样你就不用硬编码任何绝对路径保证了技能的可移植性。Features 列表是“验收标准”它不是给用户看的功能列表而是给 AI 看的“成功标志”。当 AI 执行完脚本它会回看这个列表确认生成的.docx是否真的包含了“可点击的超链接”、“Courier New 的代码块”。如果某一项不满足它可能会尝试重新执行或向用户报告问题。因此Features 必须是可验证、可观察的。Requirements 列表是“调试线索”当技能运行失败时用户或你的第一反应就是检查这些依赖是否安装。把它列在这里相当于为未来的故障排查埋下了路标。3.3 获取并理解核心转换脚本教程提到核心的 Python 脚本notebook_to_docx.py有 490 行不适合全文粘贴。但作为一位负责任的开发者你绝不能把它当作一个黑盒来使用。我们必须理解它的核心逻辑才能在出问题时快速定位。请访问官方 Gist 链接此处省略具体 URL你可在原始教程中找到下载notebook_to_docx.py文件并将其保存到~/.openclaw/skills/notebook-to-docx/目录下。现在打开这个 Python 文件。我们不需要逐行阅读而是聚焦于它的主入口函数convert_notebook_to_docx。以下是其精简后的核心逻辑def convert_notebook_to_docx(notebook_path, output_pathNone): # 1. 解析输入路径 notebook_path Path(notebook_path) if output_path is None: output_path notebook_path.with_suffix(.docx) else: output_path Path(output_path) # 2. 读取并解析 Jupyter Notebook JSON with open(notebook_path, r, encodingutf-8) as f: nb nbformat.read(f, as_version4) # 3. 创建一个新的 Word 文档对象 doc Document() create_styles(doc) # 这个函数定义了 Poppins 和 Courier New 字体 # 4. 遍历 Notebook 的每一个 Cell for cell in nb.cells: if cell.cell_type markdown: process_markdown_cell(doc, cell.source, base_path) elif cell.cell_type code: process_code_cell(doc, cell.source, cell.get(outputs, [])) # 5. 保存文档 doc.save(output_path) print(fConverted: {notebook_path} - {output_path}) return output_path这个函数的流程完美对应了SKILL.md中的Features列表create_styles(doc)确保了字体的统一process_markdown_cell处理了标题、加粗、斜体、超链接、表格process_code_cell处理了代码块的语法高亮通过语言名和字体cell.get(outputs, [])确保了图片通常是png或jpeg格式能被正确提取并嵌入。实操心得我在第一次使用这个脚本时发现生成的 Word 文档里图片的 Alt 文本是空的。排查后发现脚本中process_markdown_cell函数对语法的解析不够健壮。我的修复方案是在process_markdown_cell内部对img标签的alt属性做了显式提取和设置。这说明即使使用社区脚本你也必须具备基本的 Python 调试能力。把脚本当作一个“可修改的组件”而不是一个“不可触碰的神龛”是高级技能开发者的必备心态。3.4 测试与调试让技能从“能跑”到“稳跑”技能文件创建完毕脚本也已就位。现在是见证奇迹的时刻——也是暴露问题的时刻。第一步重启 OpenClaw 或等待热加载OpenClaw 在启动时会扫描~/.openclaw/skills/目录。虽然它有文件监视器但为了确保万无一失我建议你重启 OpenClaw 的 Telegram Bot。在 Telegram 中向你的 Bot 发送/restart命令如果支持或者直接在终端中CtrlC停止进程再重新运行openclaw命令。第二步触发技能在 Telegram 的聊天窗口中输入/notebook-to-docx然后按空格接着输入你的测试 notebook 的绝对路径。例如/notebook-to-docx /home/yourname/projects/q3-report/data_analysis.ipynb第三步观察日志与结果此时OpenClaw 的终端会输出类似这样的日志[INFO] Executing skill: notebook-to-docx [INFO] Running command: uv run --with nbformat --with python-docx --with Pillow python /home/yourname/.openclaw/skills/notebook-to-docx/notebook_to_docx.py /home/yourname/projects/q3-report/data_analysis.ipynb [INFO] Converted: /home/yourname/projects/q3-report/data_analysis.ipynb - /home/yourname/projects/q3-report/data_analysis.docx如果一切顺利你应该能在 Telegram 中收到一个.docx文件。下载它用 Word 打开逐一核对SKILL.md中列出的Features。常见问题与排查问题Telegram 中没有任何反应也没有错误提示。排查检查 OpenClaw 终端日志。最常见的原因是SKILL.md的 YAML 前言格式错误比如metadata字段用了多行 YAML。将metadata改为单行 JSON重启即可。问题终端报错Command uv not found。排查你没有安装uv。运行curl -LsSf https://astral.sh/uv/install.sh | sh进行安装并确保~/.local/bin或uv安装路径在你的PATH环境变量中。echo $PATH可以查看。问题生成的 Word 文档里代码块是灰色背景但字体不是 Courier New。排查这通常是因为python-docx的样式继承逻辑与脚本中的create_styles函数不匹配。打开notebook_to_docx.py找到create_styles函数确认它是否为CodeBlock样式设置了font.name Courier New。如果没有手动添加。注意在测试阶段务必使用一个内容简单、结构清晰的 notebook 作为测试样本。不要一上来就用你那个有 50 个 cell、嵌入了 10 张图、还调用了 Matplotlib 的复杂 notebook。先让它“能跑”再让它“跑好”。4. 进阶实战构建 Nano Banana Pro 图像生成技能如果说notebook-to-docx是一个“本地文件处理”技能那么nano-banana-pro就是一个典型的“外部 API 集成”技能。它引入了全新的挑战凭证管理、网络超时、API 限流、以及最重要的——如何让 AI 严格遵守你的模型选择指令。这个技能的构建过程将彻底刷新你对 OpenClaw 安全模型和行为控制的理解。4.1 创建技能骨架与强化元数据和上一个技能一样我们先创建目录和SKILL.md文件。mkdir -p ~/.openclaw/skills/nano-banana-pro touch ~/.openclaw/skills/nano-banana-pro/SKILL.md现在打开SKILL.md编写 YAML 前言。这一次元数据会变得丰富得多因为它需要同时处理二进制依赖和环境变量。--- name: nano-banana-pro description: Generate or edit images via Gemini 3 Pro Image on Replicate user-invocable: true metadata: {openclaw: {emoji: , requires: {env: [REPLICATE_API_TOKEN], bins: [uv]}, primaryEnv: REPLICATE_API_TOKEN}} ---对比上一个技能这里有三处关键升级emoji: 这个字段会在 Telegram 的 slash 命令列表中显示一个颜文字图标极大地提升了 UX。用户扫一眼就能知道这是个图像相关的技能。requires.env: [REPLICATE_API_TOKEN]: 这是安全的第一道闸门。它告诉 OpenClaw“在加载这个技能之前请先检查我的环境变量里有没有REPLICATE_API_TOKEN。如果没有就别加载了。” 这比在脚本里os.getenv()然后报错要优雅得多。primaryEnv: REPLICATE_API_TOKEN: 这是一个精妙的“快捷方式映射”。它意味着在后续的openclaw.json配置中我们可以用apiKey这个更短、更语义化的键名来指向这个长环境变量名。这大大简化了配置文件的书写。4.2 编写 SKILL.md 主体从“能用”到“可控”主体部分的编写同样遵循“Usage - Options - Tips - Rules”的结构。但这一次“Rules”部分不再是可选项而是强制项。# Nano Banana Pro Image Generator Generate and edit images using Googles Nano Banana Pro model via the Replicate API. ## Usage Run the generation script: uv run --with replicate python {baseDir}/generate.py --prompt user prompt [--aspect-ratio 1:1] [--output image.png] ## Options - --prompt: The image description (required) - --aspect-ratio: Ratio like 1:1, 4:3, 16:9 (default: 1:1) - --output: Output file path (default: generated_image.png) ## Tips - For text in images, be specific about fonts, size, and placement - The model supports resolutions up to 2K - Safety filtering is on by default ## Rules - Only use the google/nano-banana-pro model. Never fall back to other models like google/nano-banana or any alternative. If the model is unavailable or rate-limited, report the error to the user and stop. - After generating an image, send the image file directly in the chat. Do not just save it to the workspace silently.这里的Rules部分是整个技能的灵魂所在。它直接回应了教程中提到的那个“服务不可用”的真实案例。第一条规则用最斩钉截铁的语言封死了 AI 的所有“灵活变通”之路。第二条规则则解决了另一个常见痛点很多技能在生成文件后只是默默地把它存到硬盘然后对用户说“已完成”。但对于图像生成这种强交互场景用户需要的是“所见即所得”的即时反馈。send the image file directly in the chat这句话就是对 OpenClaw Agent 的明确指令它会调用 Telegram 的文件上传 API将生成的图片直接发送到当前聊天窗口。4.3 编写 API 调用脚本安全、健壮、可调试generate.py是这个技能的心脏。它的代码量不大但每一行都关乎成败。请创建该文件touch ~/.openclaw/skills/nano-banana-pro/generate.py然后将以下代码粘贴进去import replicate import urllib.request import argparse import sys import os def main(): parser argparse.ArgumentParser(descriptionGenerate images with Nano Banana Pro) parser.add_argument(--prompt, requiredTrue, helpThe image description) parser.add_argument(--aspect-ratio, default1:1, helpAspect ratio (e.g., 1:1, 4:3)) parser.add_argument(--output, defaultgenerated_image.png, helpOutput file path) args parser.parse_args() try: # 调用 Replicate API output replicate.run( google/nano-banana-pro, input{ prompt: args.prompt, aspect_ratio: args.aspect_ratio, output_format: png, safety_filter_level: block_only_high } ) # Replicate 返回的是一个 URL 列表或单个 URL if isinstance(output, list): url str(output[0]) else: url str(output) # 下载图片 urllib.request.urlretrieve(url, args.output) print(fImage saved to {args.output}) except Exception as e: # 关键捕获所有异常并打印清晰的错误信息 print(fError generating image: {str(e)}) sys.exit(1) if __name__ __main__: main()这段脚本的亮点在于其健壮性设计明确的异常处理 (try...except)它捕获了所有可能的异常网络超时、API 错误、URL 解析失败并打印出清晰的错误信息。这比让脚本崩溃然后留下一串 traceback 要友好得多。sys.exit(1)当发生错误时脚本以非零状态码退出。OpenClaw 会捕获这个状态码并将print输出的内容作为错误信息原封不动地发送给 Telegram 用户。这是技能与用户沟通的桥梁。safety_filter_level参数显式设置了安全过滤级别确保生成内容符合预期。4.4 配置 API 凭证安全隔离的黄金法则现在最关键的一步来了如何把你的REPLICATE_API_TOKEN安全地交给这个技能而又不把它暴露在你的 shell 环境中甚至不暴露在你的.bashrc文件里答案是永远不要在 shell 中export REPLICATE_API_TOKENxxx。这是最危险的做法因为任何子进程包括你无意中运行的脚本都能读取到它。正确的做法是将凭证写入 OpenClaw 的全局配置文件~/.openclaw/openclaw.json。首先确保这个文件存在。如果不存在创建一个空的 JSON 对象{}。然后向其中添加skills.entries配置块{ skills: { entries: { nano-banana-pro: { enabled: true, apiKey: r8_your_replicate_token_here, env: { REPLICATE_API_TOKEN: r8_your_replicate_token_here } } } } }这里有两个关键点apiKey字段这是对metadata.primaryEnv的呼应。它提供了一个简洁的键名让 OpenClaw 知道这个值应该被注入到REPLICATE_API_TOKEN环境变量中。env块这是一个更通用的机制。如果你的技能需要多个环境变量比如一个数据库连接字符串和一个 API Token你就可以在这里全部定义。env块中的所有变量都只会在这个技能的执行过程中临时生效执行完毕后立即清除绝对不会污染你的全局 shell 环境。这是 OpenClaw 提供的、开箱即用的“凭证沙箱”。提示r8_your_replicate_token_here是 Replicate 官网生成的 token 格式以r8_开头。请务必从 Replicate 控制台复制你自己的 token不要使用示例中的字符串。5. Docker 沙箱深度解析为你的技能穿上“防弹衣”到目前为止我们的两个技能都在宿主机上直接运行。这在开发和测试阶段非常方便但它带来了一个不容忽视的风险你的技能拥有和你登录用户完全相同的系统权限。这意味着如果notebook_to_docx.py里有一行os.system(rm -rf /)无论是恶意植入还是手滑写错它真的会删掉你的整个系统。而generate.py如果被恶意篡改它也可以轻易地读取你家目录下的所有文件并通过 API 发送到任意服务器。Docker 沙箱就是 OpenClaw 为解决这个问题而提供的终极防护方案。它不是可有可无的“高级功能”而是生产环境的强制安全基线。5.1 三种沙箱模式理解你的“安全预算”沙箱模式由~/.openclaw/openclaw.json中的agents.defaults.sandbox.mode字段控制。它有三个取值代表了三种不同的安全与性能权衡off默认零隔离最高性能。所有技能都在你的宿主机上以你的用户身份直接运行。这是开发时的默认选择因为它启动最快调试最方便。但请记住这只是“开发模式”绝不应出现在你的工作电脑上用于处理真实业务数据。non-main推荐混合模式平衡之选。你的主 Telegram 会话即你手动输入/xxx的那个聊天仍然在宿主机上运行以保证最快的响应速度和最直接的文件访问比如你直接/notebook-to-docx ./report.ipynb。而所有后台自动化任务比如一个定时检查 GitHub PR 的技能则会被自动放入 Docker 容器中运行。这是绝大多数用户的最佳起点。all最严全面隔离最高安全。每一个 OpenClaw 会话无论手动还是自动都在一个独立的 Docker 容器中运行。这是为处理高度敏感数据如金融、医疗的团队设计的。它的代价是每次会话启动都有几秒的 Docker 初始化延迟。要启用non-main模式你需要在openclaw.json中添加如下配置{ agents: { defaults: { sandbox: { mode: non-main, scope: session, workspaceAccess: ro } } } }5.2 工作区访问权限ro与rw的生死抉择workspaceAccess字段定义了沙箱容器对你的文件系统的访问权限。这是安全配置中最容易被误解的部分。none默认容器拥有一个完全隔离的、空的临时目录~/.openclaw/sandboxes/xxx。它无法读取你项目中的任何文件。这对于纯计算型技能如调用 API、数学计算是安全的但对于我们的notebook-to-docx技能这就成了死路——它根本找不到你要转换的.ipynb文件。ro推荐