数字员工结合语音智能体与AI提效软件系统推动业务创新与效率提升
2026/9/4 8:59:33
【Skills 系统从入门到精通】第 18 篇：环境变量声明——required_environment_variables 与 Secure Setup
本篇你将学到
- 技能如何声明需要的 API Key 和环境变量
- Secure Setup on Load 机制：首次加载时的安全提示流程
- 本地 CLI 与消息平台对敏感信息的不同处理
- 环境变量自动透传到沙箱的机制
- 实战：为一个需要 API Key 的技能配置安全加载
读完本篇，你将能够安全地为技能配置敏感信息，不泄露到聊天记录中。
一、问题：技能需要 API Key
1.1 场景
许多技能需要外部 API Key 才能工作：
- GIF 搜索技能需要 Tenor API Key
- Spotify 控制技能需要 Spotify API Token
- Web 搜索技能需要 Firecrawl API Key
- LLM 微调技能需要 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_KEY |
prompt | 提示文字 | Tenor API key |
help | 获取帮助（通常是申请地址） | Get a key from https://... |
required_for | 用途说明 | full functionality |
2.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 Load
3.1 本地 CLI 行为
当技能在本地 CLI 中被加载，且声明了缺失的环境变量时，Agent 会安全地提示用户：
用户：/gif-search funny cats Agent：此技能需要 TENOR_API_KEY。 获取 API Key：https://developers.google.com/tenor 请在 ~/.hermes/.env 中添加： TENOR_API_KEY=your_key_here 或者运行 hermes setup 配置。 你可以跳过配置继续使用（部分功能不可用）。用户有两个选择：
选择一：配置后继续
按提示在.env文件中添加 Key，然后重载：
echo"TENOR_API_KEY=your_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 出现在聊天记录中——聊天记录可能被截图、转发或保存在服务器上。
3.3 安全设计原则
| 原则 | 说明 |
|---|---|
| 不在聊天中输入 | 消息平台绝不接受 Key 输入 |
| 只在本地配置 | .env文件或hermes setup |
| 可跳过 | 用户可以选择不配置，技能部分可用 |
| 加密存储 | .env文件权限为 600（只有所有者可读写） |
四、环境变量自动透传
4.1 透传机制
声明在required_environment_variables中的变量，一旦配置完成，会自动透传到execute_code和terminal沙箱中。
这意味着技能的脚本可以直接使用这些变量，不需要手动传递：
# scripts/search_gif.pyimportosimportrequests# 直接使用环境变量——不需要参数传递api_key=os.environ["TENOR_API_KEY"]# 系统已经自动把它注入到执行环境中response=requests.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 weather```bash CITY="Beijing" curl-s "https://api.openweathermap.org/data/2.5/weather?q=${CITY}&appid=${OPENWEATHER_API_KEY}&units=metric"|python3-m json.toolStep 2: Get 5-day forecast
curl-s"https://api.openweathermap.org/data/2.5/forecast?q=${CITY}&appid=${OPENWEATHER_API_KEY}&units=metric"|python3-mjson.tool### 5.2 首次使用流程用户：/weather-query 查询北京天气
Agent：此技能需要 OPENWEATHER_API_KEY。
免费申请：https://openweathermap.org/api
请在 ~/.hermes/.env 中添加。
用户：（按提示操作）
- 访问 openweathermap.org 注册账号
- 获取 API Key
- echo “OPENWEATHER_API_KEY=abc123…” >> ~/.hermes/.env
- /reload
用户：/weather-query 查询北京天气
Agent：成功获取天气数据！
北京：晴，气温 25°C，湿度 45%，风速 3m/s
…
```mermaid flowchart TD A["用户调用 weather-query"] --> B{OPENWEATHER_API_KEY<br/>已配置?} 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。这是技能的非密钥配置管理机制，用于声明路径、偏好等非敏感配置项。
如果本篇内容对你有帮助，欢迎点赞收藏！有任何疑问，欢迎在评论区交流。