默认情况下，OpenClaw 会将 API 密钥和机器人令牌以明文形式存储在~/.openclaw/openclaw.json相关凭证文件中。对于本地个人使用来说，这可能没什么问题。但对于任何运行在 VPS 上、与他人共享或连接到付费服务的应用来说，这都存在着真正的风险。泄露的令牌会导致 API 密钥被盗而造成账单飙升，泄露的 Telegram 和 Discord 令牌会导致频道劫持，以及拥有读写权限的代理程序窃取数据。

好消息是，OpenClaw 内置了一个原生密钥管理系统，但大多数用户从未配置过，因为入门流程并不需要它。本指南涵盖了所有方面：密钥的当前存储位置、如何将其从明文配置中移除、如何与外部密钥存储集成、如何安全地轮换凭据以及如何在泄露造成损害之前检测到泄露。

你的秘密最终是如何曝光的

了解攻击面有助于确定缓解措施的优先级。OpenClaw 凭证在实践中泄露的方式有几种常见途径，但大多数情况下并非严重的黑客攻击。

Git 提交。有人将自己的~/.openclaw/目录置于版本控制之下，或者openclaw.json为了备份而复制到仓库中。即使是私有仓库，也可能因为一个错误的权限设置而变成公开的。预提交钩子会扫描令牌模式来捕获这种情况，但大多数人都没有启用这些钩子。

备份归档文件。标准的备份建议是使用 tar 打包~/.openclaw/。存储在 S3 存储桶中或通过未加密连接传输的未加密 tar 文件会以明文形式包含您的所有令牌。升级指南正是出于这个原因建议使用 GPG 对备份进行加密。

调试日志。以调试日志级别运行网关是进行故障排除的正确方法。如果环境变量解析日志记录过于详细，这也是将 API 密钥写入日志文件的一种方法。在将日志文件分享到任何地方之前，请检查其中是否包含原始令牌值。

MEMORY.md。这一点不太明显。如果代理程序被提示（有意或通过注入）将其配置上下文写入内存文件，则其身份验证配置文件中的令牌最终可能会出现在 MEMORY.md 文件中。这更多的是一种提示注入风险，而非配置风险，但后果相同：明文令牌存储在可能被备份、同步或索引到其他地方的文件中。

全局可读文件。Linux系统全新安装后，有时会留下~/.openclaw/系统上所有用户都可以读取的文件权限。在共享 VPS 或任何多用户系统中，这很容易导致凭证泄露。

环境变量和 .env 文件

从纯文本配置升级的第一步是将令牌移至环境变量。OpenClaw 会${VAR}在启动时解析配置字符串中的引用，并在网关重启时原子性地重新加载它们。这意味着您可以在移除实际值的同时，保持配置的结构不变。

.env 加载顺序

OpenClaw 会按以下顺序查找环境变量值，较早的来源优先：

1. 进程环境（由 systemd、Docker 或启动 Gateway 的 shell 设置）
2. .env在当前工作目录中
3. ~/.openclaw/.env（守护进程自身的环境变量文件）
4. env配置本身中的一个内联块

对于大多数配置而言，~/.openclaw/.env这是存放密钥的合适位置。它与所支持的配置保持紧密联系，不在可能进行版本控制的工作目录中，而且易于理解。一个简单的例子：

ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=123456:ABC-...
DISCORD_BOT_TOKEN=...
OPENAI_API_KEY=sk-...

然后在你的配置中引用它们：

models:
  providers:
    anthropic:
      apiKey: ${ANTHROPIC_API_KEY}
channels:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}

.env 文件卫生

.env 文件本身需要受到保护。首先是权限问题：

chmod 600 ~/.openclaw/.env
chown youruser:youruser ~/.openclaw/.env

如果您有任何内容~/.openclaw/处于版本控制之下（技能、自定义工具、工作区模板），请确保它们.env位于 . 中.gitignore。对于任何涉及 OpenClaw 配置的仓库，都值得添加一个 pre-commit hook，用于扫描明显的标记模式：

# Install truffleHog or gitleaks as a pre-commit hook
pip install pre-commit
# Or: brew install gitleaks

对于 systemd 服务部署，请避免通过 shell 加载 .env 文件，因为 shell 会将守护进程的环境变量传递给子进程。请改用 systemd 的EnvironmentFile指令，该指令会直接加载文件，而无需 shell 插值：

[Service]
EnvironmentFile=/secure/path/openclaw.env

~/.openclaw/如果您使用的是共享服务器，请将该文件放在服务器外部，并将其权限限制为服务用户。

OpenClaw 的原生 SecretRef 系统

从纯文本迁移到环境变量是一个很好的开端。完整的解决方案是 OpenClaw 的SecretRef系统，它允许您定义命名密钥提供程序，并在配置中的任何位置通过 ID 而非值引用密钥。网关会在启动时解析这些引用，如果任何引用无法解析，则会快速失败，这意味着配置错误的密钥会立即显现，而不会导致运行时故障。

提供者类型

内置提供程序类型有三种：env、file和exec。每种类型都涵盖不同的部署场景。

环境变量提供程序会读取环境变量，并可选择使用允许列表来限制可以访问的变量：

secrets:
  providers:
    default:
      source: "env"
      allowlist:
        - "ANTHROPIC_*"
        - "TELEGRAM_*"
        - "DISCORD_*"

文件提供程序可以从 JSON 文件或包含单个值的文件读取数据。当您希望将密钥保存在与 OpenClaw 配置分开管理的位置时，此功能非常有用：

secrets:
  providers:
    key_file:
      source: "file"
      path: "/secure/openclaw-keys.json"
      mode: "json"

JSON 文件格式很简单：键是你要引用的密钥 ID，值是实际的密钥。

执行提供程序运行命令并将其标准输出用作密钥值。这使得与外部密钥管理器集成成为可能：

secrets:
  providers:
    onepassword:
      source: "exec"
      command: "/opt/homebrew/bin/op"
      allowSymlinkCommand: true
      trustedDirs:
        - "/opt/homebrew"
      args: ["read", "op://Personal/OpenClaw/anthropic_key"]

在配置中引用密钥

定义好提供程序后，就可以在配置中使用keyRef对象而不是字面值来引用密钥了：

profiles:
  main:
    type: "api_key"
    keyRef:
      source: "env"
      id: "ANTHROPIC_API_KEY"
  telegram_prod:
    type: "bot_token"
    keyRef:
      source: "exec"
      provider: "onepassword"
      id: "telegram_prod_token"

如果您现有的 auth-profiles.json 文件中使用了明文令牌，OpenClaw 提供了一个迁移命令，可以清除这些明文令牌并将文件重写为使用引用：

openclaw secrets configure --skip-provider-setup

整合外部秘密仓库

执行提供程序是连接任何外部密钥管理器的桥梁。其模式始终相同：配置提供程序以调用外部工具的 CLI，并通过密钥在该存储中的路径或 ID 来引用密钥。

HashiCorp Vault

secrets:
  providers:
    vault:
      source: "exec"
      command: "vault"
      args:
        - "kv"
        - "get"
        - "-field=token"
        - "secret/openclaw/anthropic"

这假设 Vault CLI 已安装并通过身份验证（通过VAULT_TOKENVault 代理）。网关进程需要在运行时能够访问 Vault，这意味着 Vault 必须在本地运行，或者确保网关运行所在位置的网络访问权限。

AWS Secrets Manager

secrets:
  providers:
    aws_secrets:
      source: "exec"
      command: "aws"
      args:
        - "secretsmanager"
        - "get-secret-value"
        - "--secret-id"
        - "openclaw/anthropic"
        - "--query"
        - "SecretString"
        - "--output"
        - "text"

AWS CLI 需要凭证进行身份验证，理想情况下，应通过附加到 EC2 实例或 ECS 任务的 IAM 角色来实现，而不是使用静态访问密钥。IAM 策略应该仅授予secretsmanager:GetSecretValueOpenClaw 所需的特定密钥 ARN，不应授予更广泛的权限。

1Password CLI

secrets:
  providers:
    onepassword:
      source: "exec"
      command: "op"
      allowSymlinkCommand: true
      trustedDirs:
        - "/usr/local/bin"
        - "/opt/homebrew/bin"
      args:
        - "read"
        - "op://Personal/OpenClaw API Keys/anthropic"

allowSymlinkCommand: true`and`设置trustedDirs是安全约束，可防止执行提供程序被重定向到任意命令。只有受信任目录中的命令才能作为提供程序执行，这一点至关重要，因为篡改命令路径的执行提供程序存在代码执行漏洞。

Bitwarden / BWS

secrets:
  providers:
    bitwarden:
      source: "exec"
      command: "bw"
      args:
        - "get"
        - "password"
        - "OpenClaw Anthropic Key"

Bitwarden Secrets Manager (BWS) 也同样有效，如果您想要的是一款专门用于管理密钥的工具而不是密码管理器，那么它值得考虑。

Docker 和 Kubernetes 密钥

对于容器化部署，请使用指向已挂载密钥路径的文件提供程序。Docker Swarm 和 Kubernetes/run/secrets/默认都将密钥挂载到以下位置：

secrets:
  providers:
    container_secrets:
      source: "file"
      path: "/run/secrets/anthropic_key"
      mode: "singleValue"

它可以与 Docker Compose 的secrets:块和 Kubernetes Secret 卷完美配合。有关 Secret 如何融入多副本 Kubernetes 部署，请参阅集群指南。

轮换凭证

如果你从未在运行中的系统上轮换过已泄露或过期的凭证，那会非常棘手。但如果提前按计划进行轮换，就能消除大部分压力，因为你已经测试过整个流程。

正确旋转的步骤如下：

1. 在服务提供商的控制面板（Anthropic 控制台、Telegram BotFather、Discord 开发者门户等）中生成新密钥。暂时不要撤销旧密钥。
2. 使用新值更新密钥存储。对于基于环境的密钥，请更新~/.openclaw/.env；对于外部存储，请更新该存储中的密钥值。
3. 无需重启实时网关即可测试解析openclaw secrets list：显示屏蔽值并确认提供商可以解析每个引用。
4. 重启网关以原子性地获取新值。如果任何密钥无法解析，网关会在启动时快速失败，因此配置错误的轮换机制会在流量到达新凭证之前立即显现出来。
5. 验证连接，以openclaw channels status --probe确认每个通道都使用新令牌进行身份验证。
6. 只有在确认新密钥有效后才能撤销旧密钥。很多人匆忙之中会忽略这一步骤，事后却后悔不已。

每个集成采用最小权限原则

使用同一个 API 密钥虽然方便，但也存在风险。如果该密钥泄露，所有集成都会同时暴露。更好的做法是为每个集成和每个代理使用单独的密钥，并限制其权限范围，使其仅包含实际所需的最低权限。

实际上，这意味着：一个 Anthropic 密钥用于您的主代理，一个单独的密钥用于后台定时任务代理（可能需要使用受限权限），Telegram 和 Discord 的机器人令牌按频道分配，Gmail 和 Google 日历集成使用单独的 OAuth 凭据。有关如何将 OAuth 凭据限定为特定权限而非完全帐户访问权限，请参阅Gmail 集成指南和Slack 集成指南。

对于在公共通道中运行且输入未经信任的代理，即使代理的 API 密钥拥有更广泛的权限，也应在工具的允许/拒绝配置中拒绝执行和 Webhook 工具。纵深防御：令牌的权限范围不应过大，工具的访问权限也不应过大。

泄漏审计

OpenClaw 包含一个密钥审计命令，用于扫描已知的凭证位置以查找明文令牌：

openclaw secrets audit --check

此操作会检查auth-profiles.json旧版auth.json文件以及其他通常存放明文令牌的位置。请在每次配置更改和升级后运行此操作，因为升级有时会生成旧版明文格式的新凭据文件。

除了系统自带的审计工具之外，一些外部工具也值得添加到您的工作流程中：

• 在任何修改 OpenClaw 配置的仓库中，都应使用truffleHog 或 gitleaks作为 pre-commit hooks。这些 hooks 会在提交之前扫描高熵字符串和已知的标记模式。
• 如果您以调试日志级别运行，请手动搜索日志文件grep -r "sk-ant\|sk-\|Bearer" ~/.openclaw/logs/： 。日志中出现的令牌值表明解析或日志记录管道中的某些部分过于冗长。
• 对备份文件进行权限审核：任何.tgz包含备份文件的备份~/.openclaw/都应加密。请检查您在故障排除过程中是否创建了任何未加密的存档文件，并且忘记将其删除。

对于基于 OTEL 的监控，OpenClaw 默认会从跟踪和日志中删除密钥值。如果您在 Datadog 或 Grafana 跟踪中看到令牌值，请检查是否有自定义技能或工具显式地记录了环境变量。

该安全最佳实践指南涵盖了除机密信息之外的更广泛的运营安全方面。