第18篇-环境变量声明-required-environment-variables与Secure-Setup

【Skills 系统从入门到精通】第 18 篇环境变量声明——required_environment_variables 与 Secure Setup本篇你将学到技能如何声明需要的 API Key 和环境变量Secure Setup on Load 机制首次加载时的安全提示流程本地 CLI 与消息平台对敏感信息的不同处理环境变量自动透传到沙箱的机制实战为一个需要 API Key 的技能配置安全加载读完本篇你将能够安全地为技能配置敏感信息不泄露到聊天记录中。一、问题技能需要 API Key1.1 场景许多技能需要外部 API Key 才能工作GIF 搜索技能需要 Tenor API KeySpotify 控制技能需要 Spotify API TokenWeb 搜索技能需要 Firecrawl API KeyLLM 微调技能需要 HuggingFace Token如果技能没有声明这些依赖用户调用时会直接失败——Agent 尝试运行脚本脚本发现没有 API Key报错。1.2 声明 vs 消失有些系统采用没有 API Key 就隐藏技能的策略。但 Skills 系统选择了更友好的方式技能始终可见但加载时提示用户配置缺失的变量。这确保了用户知道这个技能存在可以决定是否去申请 API Key不会因为一个变量缺失就完全看不到技能配置完成后技能立即可用不需要重装是否技能声明环境变量调用时变量已配置?正常加载执行技能仍然可见加载时安全提示引导配置 不隐藏技能配置后立即可用二、required_environment_variables 字段2.1 字段结构在 Frontmatter 中声明required_environment_variables:-name:TENOR_API_KEYprompt:Tenor API keyhelp:Get a key from https://developers.google.com/tenorrequired_for:full functionality各子字段字段说明示例name环境变量名TENOR_API_KEYprompt提示文字Tenor API keyhelp获取帮助通常是申请地址Get a key from https://...required_for用途说明full functionality2.2 多变量声明一个技能可以需要多个环境变量required_environment_variables:-name:SPOTIFY_CLIENT_IDprompt:Spotify Client IDhelp:Create an app at https://developer.spotify.comrequired_for:authentication-name:SPOTIFY_CLIENT_SECRETprompt:Spotify Client Secrethelp:Create an app at https://developer.spotify.comrequired_for:authentication-name:SPOTIFY_REDIRECT_URIprompt:Spotify Redirect URIhelp:Use http://localhost:8888/callbackrequired_for:OAuth flow三、Secure Setup on Load3.1 本地 CLI 行为当技能在本地 CLI 中被加载且声明了缺失的环境变量时Agent 会安全地提示用户用户/gif-search funny cats Agent此技能需要 TENOR_API_KEY。 获取 API Keyhttps://developers.google.com/tenor 请在 ~/.hermes/.env 中添加 TENOR_API_KEYyour_key_here 或者运行 hermes setup 配置。 你可以跳过配置继续使用部分功能不可用。用户有两个选择选择一配置后继续按提示在.env文件中添加 Key然后重载echoTENOR_API_KEYyour_key_here~/.hermes/.env在会话中执行/reload重新加载环境变量技能就可以正常使用了。选择二跳过配置用户可以选择跳过——技能仍然加载但与 API Key 相关的功能不可用。Agent 会尽力用已有能力完成任务。3.2 消息平台行为在 Telegram、Discord 等 Gateway 平台上行为完全不同用户Telegram/gif-search funny cats Agent此技能需要 TENOR_API_KEY。 出于安全考虑请不要在聊天中输入 API Key。 请在本地终端运行 hermes setup 或编辑 ~/.hermes/.env 配置。消息平台永远不在聊天中询问或接受敏感信息。这是为了防止 API Key 出现在聊天记录中——聊天记录可能被截图、转发或保存在服务器上。消息平台本地CLI用户消息平台本地CLI用户引导到本地终端配置聊天记录永不包含密钥斜杠命令调用技能安全提示 配置方法可在 .env 添加或 hermes setup同一技能提示存在缺失变量明确说不要在聊天中输入 Key3.3 安全设计原则原则说明不在聊天中输入消息平台绝不接受 Key 输入只在本地配置.env文件或hermes setup可跳过用户可以选择不配置技能部分可用加密存储.env文件权限为 600只有所有者可读写四、环境变量自动透传4.1 透传机制声明在required_environment_variables中的变量一旦配置完成会自动透传到execute_code和terminal沙箱中。这意味着技能的脚本可以直接使用这些变量不需要手动传递声明变量required_environment_variables配置到 .env权限600技能加载自动透传execute_code 沙箱os.environ 直接读取terminal 沙箱脚本直接使用# scripts/search_gif.pyimportosimportrequests# 直接使用环境变量——不需要参数传递api_keyos.environ[TENOR_API_KEY]# 系统已经自动把它注入到执行环境中responserequests.get(https://tenor.googleapis.com/v2/search,params{key:api_key,q:query})4.2 terminal.env_passthrough如果技能需要使用非技能声明的环境变量比如系统中已有的变量需要通过terminal.env_passthrough配置# ~/.hermes/config.yamlterminal:env_passthrough:-GITHUB_TOKEN-DOCKER_REGISTRY_PASSWORD这些变量也会透传到 terminal 沙箱。五、实战配置一个需要 API Key 的技能5.1 技能编写创建一个天气查询技能---name:weather-querydescription:Use when checking weather. Current conditions and forecast via OpenWeatherMap API.version:1.0.0required_environment_variables:-name:OPENWEATHER_API_KEYprompt:OpenWeatherMap API keyhelp:Get a free key from https://openweathermap.org/apirequired_for:querying weather datametadata:hermes:tags:[weather,api,utility]category:productivity---# Weather Query## Procedure### Step 1: Get current weatherbash CITYBeijing curl-s https://api.openweathermap.org/data/2.5/weather?q${CITY}appid${OPENWEATHER_API_KEY}unitsmetric|python3-m json.toolStep 2: Get 5-day forecastcurl-shttps://api.openweathermap.org/data/2.5/forecast?q${CITY}appid${OPENWEATHER_API_KEY}unitsmetric|python3-mjson.tool### 5.2 首次使用流程用户/weather-query 查询北京天气Agent此技能需要 OPENWEATHER_API_KEY。免费申请https://openweathermap.org/api请在 ~/.hermes/.env 中添加。用户按提示操作访问 openweathermap.org 注册账号获取 API Keyecho “OPENWEATHER_API_KEYabc123…” ~/.hermes/.env/reload用户/weather-query 查询北京天气Agent成功获取天气数据北京晴气温 25°C湿度 45%风速 3m/s…mermaid flowchart TD A[用户调用 weather-query] -- B{OPENWEATHER_API_KEYbr/已配置?} B --|否| C[Agent 提示申请地址br/与配置方法] C -- D[注册获取 Key] D -- E[写入 .env 文件] E -- F[会话内 reload] F -- G[再次调用] B --|是| H[直接执行查询] G -- H H -- I[返回天气数据]本篇小结知识点核心内容声明机制required_environment_variables 字段声明依赖技能不消失缺失变量时技能仍可见加载时提示CLI 行为安全提示用户配置可跳过Gateway 行为绝不在聊天中接受 Key引导到本地配置自动透传声明的变量自动注入 execute_code 和 terminal 沙箱env_passthrough非技能声明的系统变量通过 config.yaml 配置透传安全原则Key 只存 .env 文件不在聊天中输入下篇预告下一篇是第四模块的最后一篇——Skill Config Settings。这是技能的非密钥配置管理机制用于声明路径、偏好等非敏感配置项。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。