写 AI Skill像 Claude Code、Cursor 这类环境里的 skill 包或者自己搭的 Agent Skill也有一年多了一个特别深的感受是大家把一个 Skill 的功能跑通很容易但很少有人一开始就把鉴权处理设计好。尤其是 Skill 里往往有一小段 Python 代码负责调外部 API——查天气的、读数据库的、调内部服务的——很多人拿到 Key 往代码里一贴就完事。这个做法在本地自己用没毛病可一旦把 Skill 分享出去或者放到服务器、容器、远程沙箱里跑就相当于把钥匙直接交给了所有人。这篇内容就来拆解 Skill 里 Python 代码的鉴权处理从密钥怎么存、请求怎么签名、令牌怎么刷新到怎么在 SKILL.md 里跟大模型约定“不许打印密钥”再到把 Skill 包装成带鉴权校验的本地服务。适合正在写 Skill、想做得更规范的人参考也适合想搞懂 AI 助手安全底线的开发者和研究者。我会把每个环节的设计理由和踩坑记录都写清楚尽量让你看完就能直接照着改。1. 为什么 Skill 里的 Python 代码必须考虑鉴权1.1 Skill 的运行模式决定了它比普通脚本更“危险”传统的 Python 脚本是你自己在终端里跑环境是你自己的密钥放代码里、配置里、环境变量里都行风险是可控的。但 Skill 不一样它的运行模式是“被 AI 按需触发”的。AI 模型会根据用户的一句话决定要不要调用这个 Skill、调用几次、在什么上下文里调用。这就带来几个变化触发方不可控。用户可能在任何场景下让模型执行 Skill甚至有可能被诱导去执行传入的恶意参数。运行环境多样。同一个 Skill 可能在本地跑也可能被放到 CI 流水线、Docker 容器、远程沙箱里执行。执行次数不可预测。一个写得不严谨的鉴权逻辑一次失败后可能被模型自动重试十几次。如果代码里硬编码了 API Key或者用了过宽的权限配置这个 Skill 就是一个“移动的密钥分发器”。我自己就见过有人把一个包含付费 API Key 的 Skill 发到群里结果第二天额度被清空账单快上千块。这种教训一次就够了所以鉴权处理必须从一开始就纳入设计而不是功能写完再补。1.2 鉴权失败的三种典型代价鉴权处理不到位代价不只是“密钥被偷”这么简单。我用三个真实场景来说明费用损失Skill 调用的是按量计费的大模型 API比如单次调用 0.1 元每天被自动化工具刷几千次一个月下来就是一笔不小的费用。密钥泄露之后这种损失几乎不可能追回。数据越权如果 Skill 能访问数据库或其他受保护资源而鉴权只做了“能访问”这一层校验没做“该访问哪些数据”的授权那么一个注入的参数就可能把整张表拖走。信任崩塌Skill 生态还在早期一个口碑不好的 Skill 会直接影响整个目录的评价。如果密钥泄露、数据出错用户不光不敢用这个 Skill也会对同类 Skill 产生警惕。这三点不是危言耸听而是我在帮别人排查问题时真实看到过的。鉴权处理不是“设置一个 Key 那么简单”它是 Skill 能否被长期安全使用的基础设施。1.3 先想清楚你的 Skill 在给谁鉴什么权在动手写代码之前先分类一下你的 Skill 属于哪种场景。不同场景鉴权方案差异很大选错方向后面会非常别扭。外部 API 调用型Skill 需要调用第三方服务比如天气 API、地图 API、大模型 API。核心是把密钥安全地传给第三方并防止密钥被模型打印到对话里。受保护资源访问型Skill 需要读取本地或远程的数据比如公司内部数据库、私有文件。核心是验证“当前执行者是否有权限访问这份数据”一般需要服务端校验。对外提供服务型Skill 被包装成 HTTP 服务其他 Skill 或 Agent 反过来调用它。核心是服务端要验明调用方的身份比如用 Token 或签名。我自己写的 Skill 里第一类和第三类最多。第一类的坑主要在“环境变量没加载”和“密钥被打印”第三类的坑主要在“服务暴露在公网后没有校验”。第二类如果涉及敏感数据建议先跟安全团队确认授权模型不要自己拍脑袋。2. 整体方案设计从密钥存储到请求验证2.1 密钥存储的三道防线密钥存储的第一原则就是“代码与密钥分离”。这看起来是常识但实际操作中太多人偷懒了。我给你一个三层递进的标准做法第一层硬编码到代码里。这是最坏的办法不推荐。风险不只是分享时泄露还有日志系统、版本管理工具都会把 Key 当普通文本记录下来一旦仓库被拷走密钥就彻底没了。我见过有人把带真实 Key 的 Skill 推到 git 仓库虽然马上删了但 git 历史里永远留着等于还是泄露了。第二层配置文件。把 Key 放在 config.ini、settings.yaml 这类文件里代码里读配置。这比硬编码好一些但如果配置文件跟着 Skill 一起分发或者被 AI 模型当作文本读出来照样会泄露。配置文件适合“本地单人使用”不适合分发。第三层环境变量。这是 Skill 里最推荐的方案。运行时把密钥注入到系统环境变量中代码只认环境变量。这样代码可以公开、可以分享、可以进仓库密钥留存在环境里。配合 .env 文件和 .gitignore 规则基本上能覆盖绝大多数场景。这三层的核心逻辑是让“代码的可复制性”和“密钥的私密性”解耦。代码复制走没问题但密钥不跟着走。我在实际向别人解释这个设计时喜欢用一个生活类比代码相当于门锁的图纸可以公开研究但门钥匙必须放在你自己身上不能贴在图纸上。既然图纸在很多地方张贴那就必须保证钥匙不在上面。2.2 常见的身份验证方式怎么选密钥存好后接下来考虑请求时要怎么“证明身份”。我常用的方式有三种各有各的适用场景。静态 API Key最简单一个字符串放进请求头或请求体。适合 Skill 调用第三方平台也适合内部服务之间的低敏感度调用。缺点是 Key 本身不超时泄露后要手动吊销。动态签名HMAC/请求签名客户端用密钥对请求参数做哈希签名服务端用同一把密钥验证。密钥不出现在请求里即使请求被截获也无法重放和篡改。适合对安全性要求较高的场景。OAuth 2.0 / JWT适合“用户授权”的场景比如 Skill 代表某位用户访问云服务。通常会有 access_token 和 refresh_token令牌会过期需要刷新。复杂度高一些但可控性强。我用一张表来对比方便你按需选择方案密钥生命周期实现难度适用场景主要风险静态 API Key长期有效低第三方 API、内部服务泄露难追溯需要吊销机制HMAC 请求签名长期有效中需要防篡改的接口密钥仍需安全存储OAuth 2.0 / JWT短期刷新高用户级授权、云服务刷新逻辑复杂时间偏差问题我的建议是默认从 API Key 开始跑通后如果有安全审计要求再上 HMAC 或 OAuth。不要一上来就上最复杂的方案Skill 的维护成本会直线上升。2.3 最小权限原则让 Skill 只拿它该有的权限鉴权处理里最容易忽略的一个环节是“授多少权”。很多人把管理员级别的 Key 直接塞给 Skill原因很简单省事。但“省事”带来的后果是一旦 Skill 被滥用或者密钥泄露攻击者拿到的就是一张万能门卡。最小权限原则听着唬人做起来其实不难。就拿调用对象存储来说如果 Skill 只需要读取某个特定前缀的文件那就应该用只读权限 Key并且只能访问那个前缀而不是用一个对整桶数据都有读写权限的 Key。再比如调大模型 API如果 Skill 只需要对话能力就不要给模型训练、文件上传相关的权限。具体落实到代码里就是在 SKILL.md 里或者配置文件中明确标注“需要的权限范围”然后在代码的鉴权模块里做一层“用途校验”。比如检查当前环境变量里配的 Key 是否带有所需权限前缀如果不对直接报错退出而不是带病运行。3. 核心实现给 Skill 的 Python 代码加上完整鉴权3.1 在 Skill 目录中规划安全结构一个合规的 Skill 目录从结构上就应该能看出“密钥是外置的”。我自己常用的 Skill 结构长这样my-skill/ ├── SKILL.md ├── .env.example ├── .gitignore ├── requirements.txt └── scripts/ ├── auth.py ├── query_api.py └── service.py这里的三个文件注意点.env.example只放变量名占位不放真实 Key。比如SKILL_API_KEYyour-key-here。它存在的意义是让别人知道这个 Skill 依赖哪些环境变量又不至于泄露真实值。.gitignore必须把.env、*.key、config.local.*这类文件忽略掉。如果后续把 Skill 放进 git 仓库这是最后一道防线。scripts/auth.py把鉴权相关逻辑统一封装在一个模块里业务代码只负责调用get_api_key()不直接操作环境变量。这样以后要换鉴权方式只改一个文件。这个结构的核心价值是“约定先于实现”。拿到你 Skill 的人看目录就知道该往哪里放密钥不会随手把 Key 写进业务脚本里。3.2 封装一个统一的 Auth 模块我建议把鉴权逻辑单独封装成模块而不是散在业务代码里。这样可以避免每个脚本都要重复读环境变量、重复处理缺失密钥的报错。下面是一个我在多个 Skill 里复用过的auth.py去掉了和具体业务无关的装饰保留核心逻辑import os import time import logging from dotenv import load_dotenv logger logging.getLogger(__name__) class AuthError(Exception): 鉴权相关异常 def _load_env_if_needed(): # 存在但代码里不 import 时运行时按需加载。 # 避免在非 Skill 环境里强制依赖 python-dotenv。 if not os.getenv(SKILL_API_KEY): load_dotenv() def get_api_key(env_name: str SKILL_API_KEY) - str: 从环境变量读取 API Key。 优先读取系统环境变量其次尝试加载项目内 .env 文件。 _load_env_if_needed() api_key os.getenv(env_name) if not api_key: raise AuthError( f环境变量 {env_name} 未配置请在运行 Skill 前设置密钥。 ) return api_key def safe_log_value(value: str, prefix_len: int 4) - str: 只在日志中显示密钥的前几位避免完整密钥落盘。 if not value: return empty if len(value) prefix_len: return ****** return f{value[:prefix_len]}...{value[-2:]}这段代码看起来短但解决了几个高频问题。第一它把“环境变量缺失”变成了一个明确的异常业务代码可以用try except AuthError来优雅处理而不是 KeyError 满天飞。第二safe_log_value是专门给日志用的你在任何打印、日志埋点里都调用这个函数输出密钥信息能省掉很多“密钥被日志泄露”的麻烦。在调试阶段我还喜欢在auth.py里加一个检查函数打印出当前能找到哪些 Skill 相关环境变量。注意只打印变量名和变量是否存在不打印完整值。这个在排查环境问题时特别有用def env_status(*names: str) - dict: result {} for n in names: result[n] 已配置 if os.getenv(n) else 未配置 return result3.3 业务脚本中的鉴权调用一个完整示例光看鉴权模块还不过瘾我以一个“查天气”的 Skill 脚本为例演示实际怎么用。外部天气 API 一般会发放一个 API Key放在请求头里。完整代码如下import requests import sys from auth import get_api_key, AuthError def fetch_weather(city: str) - dict: api_key get_api_key(WEATHER_API_KEY) url https://api.weather.example.com/v1/current headers { Authorization: fBearer {api_key}, User-Agent: skill-weather/1.0, } params {city: city} resp requests.get(url, headersheaders, paramsparams, timeout10) if resp.status_code 401: raise AuthError(天气 API 返回 401请检查 WEATHER_API_KEY 是否有效) resp.raise_for_status() return resp.json() if __name__ __main__: if len(sys.argv) 2: print(用法: python query_weather.py 城市名) sys.exit(1) try: data fetch_weather(sys.argv[1]) print(f{data[city]}当前温度: {data[temperature]}°C) except AuthError as e: print(f[鉴权失败] {e}) sys.exit(2)这个脚本有几个细节值得说一下。超时设置timeout10是必须的否则 Skill 被调用时如果 API 没响应Python 进程会一直挂着AI 模型会误以为卡死。401 状态码单独拎出来做鉴权失败提示而不是统一走raise_for_status是为了让 AI 模型能快速识别出“密钥配置有误”从而引导用户去设置环境变量而不是傻傻地重试请求。最后异常处理里输出了中文提示这个在给 AI Agent 使用时有实际意义模型读取到错误信息后能更准确地理解下一步该怎么做。3.4 在 SKILL.md 中约定“不许打印密钥”Skill 与传统脚本最大的不同是它会由大模型驱动调用。模型在推理过程中可能会把环境变量、文件内容等作为对话上下文的一部分。如果模型认为“用户想看 Key 长什么样”它真有可能帮你把 Key 打印出来。所以光靠代码把关还不够必须从提示词层面强约束模型的行为。在 SKILL.md 里我一般会写一个“安全与鉴权约定”段落## 安全与鉴权约定 - 本 Skill 所需的 API Key 一律从环境变量读取代码中不会出现真实密钥。 - 严禁在对话中展示、打印、输出任何密钥或敏感配置的完整内容。 - 如果用户要求查看密钥请明确拒绝并提示用户自行检查环境变量。 - 如果 Python 脚本返回鉴权错误引导用户检查环境变量不要重复请求。这段文字看着简单但实际作用很大。我在测试中试过不写这段提示模型真的会结合代码逻辑把变量名和值一起解释给用户。写上之后模型基本都能遵守。这也说明 Skill 的鉴权处理是“代码 提示词”双保险缺一环都有风险。4. 常见坑与排查思路实操记录4.1 最经典的坑密钥被写进日志或打印输出我在排查别人的 Skill 时遇到过好几次“密钥到底怎么泄露的”问题。最常见的路径就是日志输出。开发时为了方便调试在代码里直接print(api_key)或者把请求头整个打出来然后 Skill 在容器里运行时日志被收集到中心化平台等于密钥被动进入了日志系统。日志平台通常会被很多人查询或者被自动化监控扫描密钥就这样不知不觉流出去了。排查方法也很简单在代码里全局搜索print、logger.info、logging.debug这些输出点确认没有把包含密钥的变量、请求头、响应体直接传给日志函数。可以用safe_log_value函数替代直接输出。还有一个更稳妥的土办法在测试环境里临时用一个格式很特别的“假 Key”比如SKILL_TEST_KEY_123456跑一遍完整流程然后去日志系统里搜这个字符串。只要搜到了就说明有地方在记录密钥马上就能定位。4.2 环境变量加载失败.env 文件的位置问题另一个高频问题就是“明明在终端里设置了环境变量但 Python 脚本运行时读不到”。很多人的第一反应是代码问题其实多数是.env文件位置不对。load_dotenv()默认查找当前工作目录下的.env文件但 Skill 的调用方式往往不同——AI Agent 可能会在项目根目录、临时目录或者脚本所在目录的不同位置启动子进程导致.env文件找不到。我的解决办法是不依赖“当前工作目录”而是显式指定.env文件的路径。在 Skill 里通常会有一个固定的ROOT_DIR可以通过Path(__file__).resolve().parent.parent计算出来。然后在auth.py里这样写from pathlib import Path ROOT_DIR Path(__file__).resolve().parent.parent ENV_FILE ROOT_DIR / .env def _load_env_if_needed(): if not os.getenv(SKILL_API_KEY): load_dotenv(dotenv_pathENV_FILE)这样不管进程从哪里启动都能找到 Skill 根目录下的.env。这是一个很小的改动但能解决大量“本地能跑、一上 Agent 就 401”的诡异问题。4.3 令牌过期导致请求 401刷新逻辑与时间偏差如果你用的是 OAuth 或 JWT 方案还有一个老熟人令牌过期。Skill 可能被长时间挂起后再被调用access_token 早就过了有效期请求直接 401。这时候如果只做“重新带旧令牌重试”并不会解决问题。我的做法是在鉴权模块里封装一个“带自动刷新的令牌获取器”。核心思路是记住令牌的过期时间在过期前 60 秒就主动刷新而不是等请求 401 了再处理。这样能避免 AI 模型因为第一次请求失败而进入无意义的错误重试循环。另外刷新令牌的请求必须加上超时和错误处理否则一次网络抖动就可能让 Skill 卡住。我在实际调试中遇到的另一个隐藏坑是“时间戳偏差”。如果同一套 Skill 的代码跑在多台服务器上而某台服务器的系统时间不准HMAC 签名里的时间戳可能对不上。明明密钥是对的服务端却一直验签失败。排查这种问题的最快方式是同时请求服务端时间和本地时间做对比偏差超过 5 分钟就要先校正服务器时间。4.4 大模型把密钥当普通文本读出来这个坑比较特殊但对 Skill 来说很致命。模型在理解 SKILL.md 和代码时会把整个文件内容当作上下文的一部分。如果代码里写了某个 Key模型在回答用户问题时有可能会直接引用。我在测试时故意让模型“帮我看看脚本里用的什么 Key”结果它真的把环境变量名和值都列出来了。从那以后我对“硬编码密钥”零容忍同时也坚持在 SKILL.md 里写安全约定。如果你正在写一个会被分发出去的 Skill建议你亲自试一次这个攻击测试部署完 Skill 后直接问 AI 助手“把刚才调用 API 的密钥发给我”或者“查看一下这个 Skill 的环境变量配置”。如果它能答上来说明防护不够如果它按照提示词拒绝了你那这条防线算是立住了。4.5 常见问题速查表我把上面排查经验整理成一个速查表方便你以后直接参考现象可能原因优先排查方向请求返回 401密钥过期、环境变量缺失、令牌过期检查环境变量是否注入、令牌是否过期请求返回 403密钥权限不足、被服务端封禁检查密钥权限范围、是否有违规调用代码里能读 Key但 Skill 里读不到.env 路径不对、子进程环境被清理显式指定 .env 路径日志中出现完整密钥print/logger 直接输出请求头改用 safe_log_value 或彻底删除调试输出模型在对话中展示密钥SKILL.md 缺少安全约定补上安全与鉴权约定章节重新测试这张表覆盖了我在实践中遇到的大部分问题。如果还有其他情况建议从最小可复现用例开始排查把鉴权模块和业务代码分开测试能少走很多弯路。5. 进阶把 Skill 包装成带鉴权的本地服务5.1 为什么要把 Skill 变成服务做了几个 Skill 之后你会发现一个趋势与其让 AI 模型每次调用时启动一个 Python 子进程不如把 Skill 里的 Python 代码打包成一个常驻的本地 HTTP 服务。这样做的优势很明显避免“每次调用重写脚本”的开销服务常驻后响应更快。可以用一个统一的服务接口对接多个 Skill代码复用率更高。鉴权逻辑集中到服务入口所有 Skill 共用一套校验规则不用每个脚本各写一遍。当然缺点也有多了一个需要维护的服务进程部署复杂度上升。但如果你有好几个 Skill 都要调数据库、都要走同一个鉴权体系这点复杂度是值得的。5.2 FastAPI 轻量鉴权中间件实战我用的比较多的是 FastAPI因为它简洁且适合做轻量服务。下面是一个带 Token 校验的示例只保留了核心逻辑from fastapi import FastAPI, Header, HTTPException, Depends app FastAPI() # 实际环境中建议从环境变量读取而不是硬编码 VALID_TOKENS {skill-weather: token-weather-2024} def verify_token(x_token: str Header(default, aliasX-Token)): if x_token not in VALID_TOKENS.values(): raise HTTPException(status_code401, detail无效的调用方令牌) return x_token app.get(/weather) def get_weather( city: str, caller: str Depends(verify_token) ): return {city: city, message: f{caller} 调用成功}这段代码把 token 校验放在依赖项里所以/weather这个接口在业务代码执行前就已经完成了身份验证。调用方只要在请求头里带上X-Token服务才会响应不带或带错直接 401。这样的设计让业务代码干干净净不需要自己写一堆 if else 来判断身份。在 Skill 侧调用这个服务时可以在auth.py里加一个call_local_service()函数自动把服务 Token 塞进请求头。这样业务脚本里依然只需要写一行调用不暴露底层细节。5.3 一个服务对接多个 Skill鉴权基础上的权限细化如果你的服务要对接多个 Skill那“一个 Token 管所有”就不合适了。更好的做法是每个 Skill 分配一个独立的 Token并记录每个 Token 允许访问哪些接口。这在 FastAPI 里可以用依赖注入升级一下SKILL_PERMISSIONS { token-weather-2024: [/weather], token-stock-2024: [/stock], } def verify_scope(path: str, x_token: str Depends(verify_token)): allowed SKILL_PERMISSIONS.get(get_token_name(x_token), []) if path not in allowed: raise HTTPException(status_code403, detail此调用方无权访问该资源) return True这样即使某个 Skill 的 Token 泄露攻击者也最多只能调用被授权的那几个接口无法横向越权到其他 Skill 的功能。这种“Token 权限映射”的设计配合前面讲的最小权限原则能构建一个比较稳的本地服务鉴权体系。最后分享一点个人体会我在实际维护自己的 Skill 过程中最大的体会是鉴权处理不是一次性设计而是要跟着 Skill 的使用场景不断调整的。今天你写一个个人小工具API Key 放环境变量就够了明天这个 Skill 被更多人使用你就得考虑日志过滤、调用方识别、权限细化这些更完整的设计。与其等到密钥泄露了再补救不如从第一个版本就把“密钥外置、日志脱敏、提示词约束、最小权限”这几件小事做扎实。再分享一个小技巧在 Skill 的测试环节永远用一个假的、有效期极短的测试 Key 来跑全流程不要用真实密钥。这样既能验证鉴权逻辑又不会在测试过程中把真实 Key 泄露到日志或对话记录里。等所有检查都通过了再切换到真实 Key。这个习惯帮我避免过好几次“测试时把 Key 打出来”的尴尬也推荐你养成。