1. 当 Agent 把 API Key 写在明文配置里OpenClaw 数据加密这件事很多人第一次意识到问题是在自己把openclaw.yaml推到 Git 仓库之后。文件里躺着api_key: sk-proj-...、app_secret: x8Kj...、corp_secret: wL7n...任何一个能读仓库的人都能直接拿去用。更麻烦的是对话记录用户手机号、身份证号、订单地址、甚至临时贴进来的 Token全都以明文形式落在日志和归档文件里。敏感信息保护不是以后再说的优化项而是自建 Agent 环境里必须一开始就设计进去的能力。这篇聚焦两条主线传输层用 TLS 把网络通信锁死存储层用 AES-256 把落盘数据加密。适合已经在跑 OpenClaw Gateway、准备把配置和对话归档做安全加固的读者。我会给出可复制的配置骨架、加密模块代码、验证命令以及我自己踩过的几个坑。整套方案不依赖任何特殊网络环境全部在本地或自有服务器上完成。先明确一个分层思路后面所有配置都围绕它展开层级保护手段防的是什么传输安全TLS 1.2 / HTTPS网络中间人截获敏感信息存储安全AES-256-GCM 加密落盘硬盘被窃、日志泄露导致明文暴露访问控制环境变量 / Secret 隔离内部人员或误操作读到密钥审计追踪操作日志 脱敏归档事后无法追溯谁动了数据四层里TLS 和 AES-256 是最容易落地、收益最直接的两层。下面从环境准备开始。2. TaoToken 前置把模型接入的密钥管起来在讲加密配置之前得先解决一个现实问题OpenClaw 要调用大模型模型侧的 API Key 本身就是最敏感的凭证之一。我的做法是把模型接入统一走 TaoToken这样密钥只在一个地方配置加密和轮转的边界也更清晰。TaoToken 的定位是模型 API 聚合接入层兼容 OpenAI 风格的接口协议OpenClaw 的 provider 配置可以直接对接。对做敏感信息保护的场景来说它的价值在于你不需要在多个 provider 之间散落多套密钥收敛到一个入口后加密策略和轮转脚本只需要覆盖一处。接入信息如下建议先收藏官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基地址https://taotoken.net/api模型对话调试https://taotoken.net/console/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan长期编码/Agent 场景https://taotoken.net/console/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaudeCode Anthropic 兼容说明https://taotoken.net/doc/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite拿到 Key 之后不要写进openclaw.yaml。正确姿势是放进环境变量配置文件里只留占位符。这一步是后面 AES-256 加密方案能成立的前提——如果密钥本身就以明文躺在配置里加密存储就失去意义了。# 生成一个 32 字节主密钥AES-256 用只做一次 python3 -c import os; print(os.urandom(32).hex()) # 写入环境变量示例实际请用你的密钥管理方式 export OPENCLAW_ENCRYPTION_KEY把上面生成的64位hex粘贴到这里 export TAOTOKEN_API_KEY你的TaoToken密钥注意环境变量只是过渡方案。生产环境建议用 Secret Manager 或 KMS环境变量在printenv、进程列表、容器 inspect 里都可能泄露。3. 传输层TLS 终结配置3.1 Gateway 的 TLS 基础配置OpenClaw Gateway 默认监听明文端口局域网内用没问题一旦跨网络就必须上 TLS。下面是我实测可用的配置段写在openclaw.yaml里# openclaw.yaml - TLS 配置段 gateway: port: 18789 tls: enabled: true cert_file: /etc/openclaw/tls/cert.pem key_file: /etc/openclaw/tls/key.pem # 最低 TLS 版本1.2 以下直接拒绝 min_version: 1.2 # 加密套件白名单只保留 AEAD 类 cipher_suites: - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 auto_renew: enabled: true provider: letsencrypt domains: - openclaw.your-domain.com email: adminyour-domain.com renew_before_days: 30几个参数值得展开说。min_version: 1.2是底线TLS 1.0/1.1 已经被认为不安全很多扫描器会直接标红。cipher_suites用白名单模式只留 GCM 系列这类套件同时提供加密和完整性校验比 CBC 系列更抗攻击。auto_renew交给 Lets Encrypt 自动续期省得证书过期导致服务中断。3.2 开发环境自签证书本地开发没有公网域名用自签证书即可。一条命令生成注意subjectAltName要覆盖你实际访问的地址# 生成自签证书仅开发/测试用 openssl req -x509 -nodes -days 365 -newkey rsa:4096 \ -keyout /etc/openclaw/tls/key.pem \ -out /etc/openclaw/tls/cert.pem \ -subj /CNlocalhost \ -addext subjectAltNameDNS:localhost,IP:127.0.0.1 # 验证证书内容 openssl x509 -in /etc/openclaw/tls/cert.pem -text -noout | head -20生成后重启 Gateway用curl -k https://localhost:18789/health测试连通性。-k是跳过证书校验仅用于自签场景生产环境必须去掉否则 TLS 的意义就没了。提示自签证书只用于本地开发。生产环境务必使用受信任 CA 签发的证书否则客户端要么报错要么被迫关闭校验等于没加密。4. 存储层AES-256-GCM 加密实战4.1 加密模块实现传输层解决的是路上的安全存储层解决的是落地的安全。我用 AES-256-GCM 实现了一个加密存储模块核心设计原则有四条GCM 模式同时保证机密性和完整性每次加密生成随机 Nonce防止相同明文产生相同密文密钥从环境变量读取绝不硬编码支持密钥版本化方便后续轮转。 secure_storage.py OpenClaw 安全存储模块 - AES-256-GCM 加密 import os import json import base64 import hashlib from typing import Dict, Any from cryptography.hazmat.primitives.ciphers.aead import AESGCM class DecryptionError(Exception): 解密异常 pass class SecureStorage: 敏感数据加密存储管理器 - AES-256-GCM 认证加密同时保证机密性和完整性 - 每次加密使用随机 Nonce12字节 - 密钥从环境变量读取支持多版本轮转 def __init__(self, key_version: str v1): master_key_hex os.environ.get(OPENCLAW_ENCRYPTION_KEY) if not master_key_hex: raise ValueError( 未设置 OPENCLAW_ENCRYPTION_KEY 环境变量\n 生成密钥: python3 -c \import os; print(os.urandom(32).hex())\ ) self.key_version key_version self._keys self._derive_keys(bytes.fromhex(master_key_hex)) self._aesgcm AESGCM(self._keys[key_version]) def _derive_keys(self, master_key: bytes) - Dict[str, bytes]: 从主密钥派生多版本子密钥支持轮转 keys {} for version in [v1, v2, v3]: salt fopenclaw-key-{version}.encode() derived hashlib.pbkdf2_hmac( sha256, master_key, salt, 100000, dklen32 ) keys[version] derived return keys def encrypt(self, plaintext: str) - str: 加密字符串返回 base64(version || nonce || ciphertext) nonce os.urandom(12) plaintext_bytes plaintext.encode(utf-8) ciphertext self._aesgcm.encrypt(nonce, plaintext_bytes, None) packed self.key_version.encode() nonce ciphertext return base64.b64encode(packed).decode(ascii) def decrypt(self, encrypted: str) - str: 解密自动识别密钥版本 try: packed base64.b64decode(encrypted) version packed[:2].decode() if version not in self._keys: raise ValueError(f不支持的密钥版本: {version}) nonce packed[2:14] ciphertext packed[14:] aesgcm AESGCM(self._keys[version]) plaintext aesgcm.decrypt(nonce, ciphertext, None) return plaintext.decode(utf-8) except Exception as e: raise DecryptionError(f解密失败: {e}) def encrypt_dict(self, data: Dict[str, Any]) - str: 加密字典自动序列化为 JSON return self.encrypt(json.dumps(data, ensure_asciiFalse)) def decrypt_dict(self, encrypted: str) - Dict[str, Any]: 解密并反序列化为字典 return json.loads(self.decrypt(encrypted))这段代码里有两个细节容易被忽略。第一packed的前两个字节存的是密钥版本解密时先读版本再选密钥这样轮转期间新旧密文可以共存。第二GCM 的encrypt会自动附加认证标签如果密文被篡改decrypt会直接抛异常而不是返回错误明文——这就是完整性保护。4.2 配置文件加密占位符有了加密模块配置文件里就不该出现明文密钥了。我用ENC(...)标记加密值Gateway 启动时自动解密# openclaw.yaml - 使用加密占位符 model: providers: taotoken: base_url: https://taotoken.net/api api_key: ENC(这里放加密后的密文) channels: feishu: app_secret: ENC(这里放加密后的密文)配套的解密加载器负责在启动时把ENC()里的内容还原 config_decrypt.py 配置文件解密加载器 - 启动时自动解密 ENC() 占位符 import re import yaml from secure_storage import SecureStorage ENC_PATTERN re.compile(r^ENC\((.*)\)$) def load_config_with_decrypt(config_path: str) - dict: with open(config_path, r) as f: config yaml.safe_load(f) store SecureStorage() def decrypt_values(obj): if isinstance(obj, dict): return {k: decrypt_values(v) for k, v in obj.items()} elif isinstance(obj, list): return [decrypt_values(v) for v in obj] elif isinstance(obj, str): match ENC_PATTERN.match(obj) if match: return store.decrypt(match.group(1)) return obj return obj return decrypt_values(config)生成密文的操作很简单先加密再粘贴# 加密一个 API Key把输出粘贴到 yaml 的 ENC() 里 python3 -c from secure_storage import SecureStorage store SecureStorage() print(store.encrypt(sk-proj-your-real-key)) 5. 验证请求与成功结果配置写完必须验证否则你不知道加密到底生效没有。分三步走。第一步验证 TLS 是否真的在跑。用openssl s_client看握手信息# 检查 TLS 版本和加密套件 openssl s_client -connect localhost:18789 -tls1_2 /dev/null 2/dev/null | grep -E Protocol|Cipher预期输出类似Protocol: TLSv1.2和Cipher: ECDHE-RSA-AES256-GCM-SHA384。如果显示 TLSv1.3 也没问题说明协商到了更高版本。第二步验证加解密往返是否一致。跑一段自测from secure_storage import SecureStorage store SecureStorage() api_key sk-proj-this-is-a-secret-key-12345 encrypted store.encrypt(api_key) print(f加密后: {encrypted[:50]}...) decrypted store.decrypt(encrypted) assert decrypted api_key, 加解密不匹配 print(加解密验证通过) # 相同明文两次加密应产生不同密文 encrypted2 store.encrypt(api_key) print(f两次密文不同: {encrypted ! encrypted2})第三步验证篡改检测。手动改一个字符再解密应该报错而不是返回错误明文tampered encrypted[:-4] AAAA try: store.decrypt(tampered) print(异常篡改未被检测到) except Exception as e: print(f篡改被正确拦截: {type(e).__name__})三步都通过说明传输层和存储层的加密链路是通的。这时候再去调一次模型接口确认业务没被加密配置影响curl -s https://localhost:18789/v1/chat/completions \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]} \ | head -c 200返回正常 JSON 就说明整条链路没问题。6. 本篇常见错排查6.1 解密失败InvalidTag 报错最常见的报错是cryptography.exceptions.InvalidTag。原因通常是密钥不匹配——加密用的主密钥和解密用的不是同一个。检查OPENCLAW_ENCRYPTION_KEY是否在加密和解密两个进程里一致。另一个可能是密文在传输中被截断比如 yaml 里ENC()内容换行了。6.2 TLS 握手失败no shared cipher如果客户端报no shared cipher说明服务端配置的cipher_suites和客户端支持的不重叠。排查方法是先用openssl ciphers -v看客户端支持哪些再对照服务端白名单。开发环境可以临时放宽生产环境建议升级客户端而不是降级服务端。6.3 环境变量读不到SecureStorage初始化时报未设置环境变量但echo $OPENCLAW_ENCRYPTION_KEY明明有值。这种情况多半是进程启动方式的问题——systemd 服务、Docker 容器、supervisor 各自的环境变量注入方式不同。Docker 里要用-e或env_filesystemd 里要写Environment或EnvironmentFile。别指望 shell 里 export 的变量能自动传给守护进程。6.4 密钥轮转后旧数据读不了轮转脚本跑完发现部分旧文件解密失败。检查_derive_keys里的版本列表是否覆盖了所有历史版本。如果之前只派生到 v2现在轮转到 v3那 v1 加密的数据就找不到对应密钥了。解决办法是保留所有历史版本的派生逻辑只新增不删除。6.5 对话归档脱敏不彻底脱敏规则用正则匹配容易漏掉变体。比如手机号中间带空格、身份证最后一位是小写 x、API Key 前缀不是sk-。建议在DEFAULT_RULES基础上根据自己业务的实际数据格式补充规则并且每次归档后抽样检查几条。7. 继续把加密链路用起来整套配置跑通之后日常维护其实不复杂。密钥轮转建议 90 天一次用前面提到的版本化机制可以做到平滑切换新数据用新版本加密旧数据在后台批量重加密期间两套密钥同时可用。对话归档的脱敏规则建议做成配置项不同业务场景挂不同规则集避免一刀切。如果你还没开始接入模型建议先去 TaoToken 控制台把 API Key 建好再回来配加密——顺序反了的话密钥管理会乱。模型对话调试可以直接在控制台里试确认接口通了再写进 OpenClaw 配置。长期跑编码或 Agent 任务的话Coding Plan 那条链路也值得看一眼密钥收敛之后加密策略的维护成本会低很多。最后留一个思考AES-256-GCM 的认证加密意味着密文被改一个字节解密就会失败。这个特性在防篡改上很强但也意味着你的备份和传输环节不能对密文做任何修复性处理否则数据就废了。轮转脚本里我特意加了assert verified plaintext这一步就是为了在覆盖原文件之前确认新密文一定能解回来。这个习惯建议你也保留。