1. 为什么自定义 skill 传参总踩坑OpenClaw 的自定义 skill 一旦涉及外部服务就绕不开一个现实问题token、IP、端口、API 地址这些参数往哪放。直接写死在脚本里改一次要动代码写进 SKILL.md 的正文里模型读的时候会当成指令内容既浪费 token 又容易泄露。我试过把参数塞进 description结果模型在触发时把 token 当成了对话上下文的一部分行为变得很不稳定。真正干净的方案是把参数抽到环境变量里让 SKILL.md 只声明「我需要哪些变量」脚本运行时从os.environ读取。这样 skill 的触发逻辑和敏感配置彻底解耦换设备、换账号只需要改环境变量不用碰 skill 本体。这篇聚焦 OpenClaw 自定义 skill 通过环境变量传参的完整落地skill 目录骨架怎么摆、SKILL.md 的 metadata 怎么声明 requires.env、primaryEnv 起什么作用、脚本怎么读变量、以及 blocked/eligible 状态怎么验证。适合已经在本地跑通 OpenClaw、想给自己的 skill 加一层配置隔离的开发者。下面所有配置都可以直接复制改掉变量名就能用。2. TaoToken 前置把模型侧配置先理顺在折腾 skill 传参之前建议先把 OpenClaw 背后的模型接入配置固定下来否则 skill 调试到一半发现模型请求失败排查方向会被带偏。TaoToken 提供 OpenAI 兼容的接口OpenClaw 里配置 base_url 指向https://taotoken.net/api再填上在控制台生成的 API Key 即可。具体动作打开 TaoToken 控制台 创建密钥然后在 API Keys 管理页 复制出来。如果你只是想先确认模型能不能正常对话可以直接用 模型对话 页面发一条消息验证链路。长期跑编码类 skill 或 Agent 任务的话Coding Plan 的额度模型更适合高频调用。这一步的意义在于skill 的环境变量传参是「业务参数」模型接入是「基础设施参数」两者分开管理。基础设施参数走 OpenClaw 的模型配置业务参数走 skill 的 metadata 声明互不干扰。接入细节可以参考 接入文档配置项和 OpenAI SDK 基本一致。3. skill 目录骨架与加载优先级OpenClaw 的 skill 有三个存放位置优先级从高到低是workspace 下的skill目录、主目录下的~/.openclaw/skills、以及 npm 安装的捆绑 skill。同名 skill 冲突时按这个顺序覆盖。workspace 下的 skill 只对当前 agent 生效属于私有~/.openclaw/skills是共享的所有 agent 都能用。另外还能通过~/.openclaw/openclaw.json里的skills.load.extraDirs关联外部目录这个优先级最低。一个标准的 skill 目录长这样my-skill/ ├── SKILL.md # 必需指令 metadata ├── scripts/ # 可选可执行代码 ├── references/ # 可选文档按需读取 └── assets/ # 可选模板、资源SKILL.md 是唯一必需的文件。如果内容太长正确做法是拆到references/目录在 SKILL.md 里引用路径模型按需读取这样能显著降低 token 消耗。下面用一个智能插座控制 skill 做例子完整走一遍环境变量传参。4. SKILL.md 与 metadata 配置骨架SKILL.md 用 YAML front matter 加 Markdown 正文组成。front matter 以---开始和结束字段里name和description必填metadata用来声明环境变量依赖。关键字段含义如下字段必需说明name是skill 名称64 字符内小写字母和-组合字母开头description是功能与触发条件直接影响模型是否调用license否许可证描述metadata否元数据声明环境变量、依赖程序等metadata 里和传参最相关的是requires.env和primaryEnv。requires.env列出必须存在的环境变量缺任何一个 skill 就会被禁用primaryEnv把某个变量关联到 UI 上的「Save key」入口方便在界面里填值。可复制的 SKILL.md 骨架--- name: smart-plug-control description: Smart plug control skill for turning plug on/off. Triggers on phrases like turn off plug, turn on plug, 打开插座, 关闭插座, or similar plug control commands. metadata: { openclaw: { requires: { env: [SMART_PLUG_TOKEN, SMART_PLUG_IP] }, primaryEnv: SMART_PLUG_TOKEN } } --- # Smart Plug Control 通过环境变量读取插座 IP 和 token调用本地 HTTP 接口控制开关。 ## 使用方式 当用户要求打开或关闭插座时执行 scripts/plug.py参数从环境变量注入。注意name必须是小写字母加连字符别用下划线或大写否则加载会报错。description里把中英文触发词都写上模型识别率会高不少。5. 脚本读取环境变量与注入片段SKILL.md 声明完之后脚本侧要真正去读这些变量。Python 示例import os import requests def get_smart_plug_ip(): return os.environ.get(SMART_PLUG_IP) def get_smart_plug_token(): return os.environ.get(SMART_PLUG_TOKEN) PLUG_IP get_smart_plug_ip() PLUG_TOKEN get_smart_plug_token() def set_plug(state: str): url fhttp://{PLUG_IP}/api/switch headers {Authorization: fBearer {PLUG_TOKEN}} resp requests.post(url, json{state: state}, headersheaders, timeout5) resp.raise_for_status() return resp.json() if __name__ __main__: import sys print(set_plug(sys.argv[1]))环境变量的注入方式取决于你启动 OpenClaw 的方式。Linux/macOS 下可以在 shell 里 export或者写进~/.openclaw/openclaw.json的 env 配置段。Windows 对应C:\Users\[用户名]\.openclaw目录逻辑一致。export SMART_PLUG_IP192.168.1.50 export SMART_PLUG_TOKENyour-token-here openclaw gateway restart改完 SKILL.md 或环境变量后必须重启 gateway 才会重新加载 skill 状态。6. 验证请求与状态排查重启后切换到 skill 目录如果环境变量没配全skill 状态会变成blocked这正是我们要的效果——参数缺失时直接禁用避免运行到一半才报错。验证步骤openclaw gateway restart openclaw skill list预期看到smart-plug-control的状态。变量齐全时是eligible缺变量时是blocked。然后实际触发一次openclaw run 打开插座脚本会从环境变量拿到 IP 和 token请求本地接口返回开关结果。如果用了primaryEnvUI 上会出现「Save key」按钮填进去的值会以明文写进openclaw.json关联到SMART_PLUG_TOKEN。不需要这个入口就把 metadata 里的primaryEnv删掉。常见错误对照现象原因处理skill 一直 blockedrequires.env 里的变量没配检查 export 或 openclaw.jsonname 加载报错含大写或下划线改成小写加连字符脚本读不到变量没重启 gateway重启后重新加载触发不生效description 触发词太窄补充中英文关键词7. 继续往下走环境变量传参跑通之后skill 的配置就和代码彻底分开了。下一步可以把 token 换成加密存储或者把多个 skill 共享的变量抽到统一的 env 文件里管理。模型侧如果还没配好先去 API Keys 拿密钥接入细节看 接入文档想先验证模型对话是否正常用 模型对话 发一条消息最快。长期跑编码和 Agent 任务的话Coding Plan 的额度更划算。
