OpenClaw 凭证与密钥安全管理

2026-01-21 · 6 分钟安全运维

凭证存储结构

OpenClaw 的凭证文件分布在多个目录中，每种凭证有其固定的存储位置：

~/.openclaw/
├── credentials/
│   └── whatsapp/           # WhatsApp 频道凭证
│       ├── creds.json      # 设备认证信息
│       └── session/        # 会话密钥
├── agents/
│   └── <agent-id>/
│       └── agent/
│           └── auth-profiles.json  # 模型认证配置
└── config/
    └── openclaw.json5      # 主配置文件（含 Token）

WhatsApp 凭证管理

WhatsApp 频道的凭证在首次扫码配对后自动生成：

# 凭证目录
ls -la ~/.openclaw/credentials/whatsapp/

# 查看凭证文件权限（应为 600）
stat -c '%a %n' ~/.openclaw/credentials/whatsapp/creds.json

重要提示：切勿手动编辑 WhatsApp 凭证文件，否则可能导致设备被封禁。

模型认证配置

每个 Agent 可以有独立的模型认证信息，存储在 auth-profiles.json 中：

{
  "profiles": {
    "anthropic": {
      "provider": "anthropic",
      "apiKey": "sk-ant-xxxxxxxxxxxxx"
    },
    "openai": {
      "provider": "openai",
      "apiKey": "sk-xxxxxxxxxxxxx"
    },
    "local": {
      "provider": "ollama",
      "baseUrl": "http://localhost:11434"
    }
  }
}

环境变量方式

推荐使用环境变量存储敏感的 API 密钥，避免明文写入配置文件：

# 在 .env 或系统环境变量中设置
export OPENCLAW_ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"
export OPENCLAW_OPENAI_API_KEY="sk-xxxxxxxxxxxxx"
export OPENCLAW_GATEWAY_TOKEN="oc_gw_xxxxxxxxxxxxx"

配置文件中引用环境变量：

{
  model: {
    provider: "anthropic",
    apiKey: "${OPENCLAW_ANTHROPIC_API_KEY}"
  },
  gateway: {
    authToken: "${OPENCLAW_GATEWAY_TOKEN}"
  }
}

配对白名单

限制哪些设备或用户可以与 OpenClaw 实例配对：

{
  security: {
    pairingWhitelist: [
      "+8613800138000",
      "+8613900139000"
    ]
  }
}

密钥轮换流程

定期轮换密钥是安全运维的重要环节。推荐以下标准流程：

# 第一步：生成新的 Token
openclaw token generate --type gateway
# 输出: oc_gw_new_xxxxxxxxxxxxx

# 第二步：更新配置文件中的 Token
# 编辑 ~/.config/openclaw/openclaw.json5

# 第三步：重启网关使新 Token 生效
openclaw gateway restart

# 第四步：更新所有客户端的 Token 配置
# 通知所有使用该 Token 的客户端更新

# 第五步：验证旧 Token 已失效
curl -H "Authorization: Bearer old_token" http://localhost:8080/v1/health
# 应返回 401 Unauthorized

轮换检查清单

生成新凭证
更新配置文件
重启相关服务
逐个更新客户端
验证旧凭证已失效
记录轮换时间和操作人

文件权限设置

正确的文件权限是安全的基础：

# 配置文件：仅所有者可读写
chmod 600 ~/.config/openclaw/openclaw.json5
chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json

# 状态目录：仅所有者可读写执行
chmod 700 ~/.openclaw/credentials/
chmod 700 ~/.openclaw/agents/

# 批量修复权限
find ~/.openclaw -type f -exec chmod 600 {} \;
find ~/.openclaw -type d -exec chmod 700 {} \;

安全审计

使用内置的安全审计工具检查凭证安全状态：

# 运行安全审计
openclaw security audit

# 自动修复发现的问题
openclaw security audit --fix

审计项目包括：文件权限检查、凭证过期检测、配置安全性评估、未加密存储检测。

常见问题排查

认证失败（401）：检查 Token 是否正确，确认环境变量已加载
凭证文件丢失：检查 ~/.openclaw/credentials/ 目录权限和文件完整性
审计报告异常：按照 openclaw security audit --fix 的提示逐项修复