API Key 安全管理：Agent 场景下的密钥最佳实践

Agent 的密钥困境

AI Agent 需要大量 API Key 才能工作：LLM API、搜索引擎、数据库、云服务……每个 Key 都是一把可能的「数据泄露钥匙」。传统应用的密钥管理方案不完全适用于 Agent——因为 Agent 的代码和配置文件经常被分享、审查、开源。

方案一：环境变量（最基础）

# .env 文件（加入 .gitignore！）
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GITHUB_TOKEN=ghp_xxx

import os
api_key = os.environ.get("OPENAI_API_KEY")

优点：简单、通用 缺点：进程环境变量可被其他进程读取；.env 文件容易被意外提交

方案二：MCP Server 环境变量注入

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

优点：密钥只暴露给需要的 MCP Server，不污染全局环境 缺点：配置文件中的明文密钥仍有泄露风险

方案三：系统密钥链（推荐 macOS/Linux）

# macOS Keychain
security add-generic-password -a "openclaw" -s "openai-api-key" -w "sk-xxx"

# 读取
security find-generic-password -a "openclaw" -s "openai-api-key" -w

Fast-Agent 支持系统 KeyRing 存储 OAuth Token：

fast-agent auth login  # 自动存储到系统密钥链

方案四：HashiCorp Vault（企业级）

# 安装 Vault CLI
brew install vault

# 写入密钥
vault kv put secret/agent/openai api_key="sk-xxx"

# Agent 启动时读取
export OPENAI_API_KEY=$(vault kv get -field=api_key secret/agent/openai)

步骤：实施密钥安全检查清单

1. 审计：用 grep -r "sk-" . 检查代码中是否有硬编码密钥
2. 迁移：把所有密钥移到环境变量或密钥管理服务
3. 隔离：不同服务使用不同密钥，避免一把钥匙开所有门
4. 轮换：定期轮换 API Key，设置自动过期
5. 监控：配置 API 使用量告警，异常调用立即通知
6. 扫描：用 Snyk Agent Scan 检查 Skill 中的硬编码密钥

注意事项

• 永远不要在 SKILL.md 中写入 API Key
• .env 文件必须在 .gitignore 中
• 分享 MCP 配置时，用占位符替代真实密钥
• GitHub 的 Secret Scanning 会自动检测推送的密钥——但不要依赖它