OpenClaw Secrets Management — API Key 不再明文写配置

> 一句话版本：OpenClaw 的密钥管理功能，让你的 API Key、Token 等敏感信息不用明文写在配置文件里，而是从环境变量、本地加密文件、或密码管理器（1Password/Vault）中读取。配置文件可以安全提交到 Git。

核心内容

问题

OpenClaw 的 openclaw.json 配置文件里包含大量敏感信息：OpenAI API Key、Discord Bot Token、Telegram Token、各种 MCP Server 的密钥……如果明文写配置，就不能把配置文件提交到 Git，否则密钥泄露。

解决方案：SecretRef

把明文密钥替换为一个引用对象，指向外部密钥来源：

// 之前（明文）
{
  models: {
    providers: {
      openai: {
        apiKey: "sk-proj-abc123..." // ❌ 明文，不能提交 Git
      }
    }
  }
}

// 之后（SecretRef）
{
  models: {
    providers: {
      openai: {
        apiKey: { source: "exec", provider: "onepassword", id: "value" } // ✅ 安全
      }
    }
  }
}

三种密钥来源

Env 来源

apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" }

直接读取环境变量 $OPENAI_API_KEY。最简单的方式。

File 来源

// 配置
{
  secrets: {
    providers: {
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json", // 加密文件
        mode: "json"
      }
    }
  }
}

// 引用
apiKey: { source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

从 ~/.openclaw/secrets.json 读取，支持 JSON Pointer 路径。文件权限有检查，Windows fail-closed。

Exec 来源（最强大）

通过外部命令获取密钥，已集成三大密码管理工具：

1Password CLI：

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true,
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      }
    }
  }
}
apiKey: { source: "exec", provider: "onepassword_openai", id: "value" }

HashiCorp Vault CLI：

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
      }
    }
  }
}

sops（加密文件）：

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
      }
    }
  }
}

也支持 MCP Server 环境变量

MCP Server 的 API Key 也不用明文：

{
  plugins: {
    entries: {
      acpx: {
        config: {
          mcpServers: {
            github: {
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-github"],
              env: {
                GITHUB_PERSONAL_ACCESS_TOKEN: {
                  source: "env",
                  provider: "default",
                  id: "MCP_GITHUB_PAT"
                }
              }
            }
          }
        }
      }
    }
  }
}

运行时模型（设计精妙）

安全机制

• 文件权限检查（owner/group/permissions）
• Windows fail-closed（ACL 验证不可用时直接失败）
• 路径遍历防护（.. 路径段被拒绝）
• Symlink 验证（默认不允许，需显式 allowSymlinkCommand + trustedDirs）
• Exec 命令无 shell（直接执行二进制，防注入）
• 环境变量白名单（passEnv 只传指定变量）
• 超时和输出大小限制

分析

优势：

• 配置文件可以安全提交 Git（不含明文密钥）
• 与 1Password/Vault/sops 集成，企业级安全
• 向后兼容（明文仍然有效，SecretRef 是可选的）
• 运行时设计精良（原子交换、活跃 Surface 过滤、热路径隔离）
• 安全机制全面（文件权限、路径遍历、symlink、exec 注入防护）
• MCP Server 密钥也支持，覆盖完整

适用场景：

• 配置文件要提交 Git（最直接的收益）
• 多环境部署（dev/staging/prod 用不同密钥源）
• 团队协作（统一密钥管理，不共享明文）
• 合规要求（密钥不能以明文存储在配置文件中）

X API Key 配置示例

以 X_BEAR_TOKEN 为例，三种方式：

方式 1：env（最简单）

# ~/.bashrc
export X_BEAR_TOKEN="your-actual-key-here"

// openclaw.json
xBearToken: { source: "env", provider: "default", id: "X_BEAR_TOKEN" }

方式 2：file（本地文件，不进 Git）

// ~/.openclaw/secrets.json（明文，gitignore 排除）
{ "x": { "bearToken": "your-actual-key-here" } }

// openclaw.json
{
  secrets: {
    providers: {
      filemain: { source: "file", path: "~/.openclaw/secrets.json", mode: "json" }
    }
  }
}
xBearToken: { source: "file", provider: "filemain", id: "/x/bearToken" }

方式 3：exec + sops（加密文件，可提交 Git）

详见下方 sops 实操。

sops 实操教程

sops（Secrets OPerationS）是 Mozilla 开源的加密工具，专门加密配置文件里的密钥。文件加密后可以安全提交 Git，只有持有密钥的机器能解密。

安装

# macOS
brew install sops age

# Linux (VPS)
sudo apt install sops
curl -fsSL https://github.com/FiloSottile/age/releases/latest/download/age-linux-amd64.tar.gz | sudo tar xz -C /usr/local/bin

生成密钥

age-keygen -o ~/.config/sops/keys.txt
# Public key: age1qyq0z6g5x9ek3k3yqn8w0rc2pt4c...

创建配置 `.sops.yaml`（项目根目录）

keys:
  - &admin age1qyq0z6g5x9ek3k3yqn8w0rc2pt4c...
creation_rules:
  - path_regex: secrets\.enc\.json$
    key_groups:
      - age:
          - *admin

加密文件

# 创建明文
cat > ~/.openclaw/secrets.json << 'EOF'
{
  "x": { "bearToken": "AAAAAAAAAAAAAAAAAAAAACAg8AEAAAAAX..." },
  "openai": { "apiKey": "sk-proj-abc123..." }
}
EOF

# 加密 → 生成 secrets.enc.json
sops -e ~/.openclaw/secrets.json > ~/.openclaw/secrets.enc.json

加密后的文件（可提交 Git）：

{
  "x": { "bearToken": "ENC[AES256_GCM,data:kx8J...,iv:...,tag:...,type:str]" },
  "openai": { "apiKey": "ENC[AES256_GCM,data:7fN2...,iv:...,tag:...,type:str]" },
  "sops": { "age": ["age1qyq0z6g..."], "lastmodified": "2026-04-12T06:00:00Z" }
}

OpenClaw 配置

{
  secrets: {
    providers: {
      sops_main: {
        source: "exec",
        command: "/usr/local/bin/sops",
        args: ["-d", "--extract", '["x"]["bearToken"]', "/home/jay/.openclaw/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"]
      }
    }
  }
}
xBearToken: { source: "exec", provider: "sops_main", id: "value" }

# 让 sops 找到密钥
echo 'export SOPS_AGE_KEY_FILE=~/.config/sops/keys.txt' >> ~/.bashrc
source ~/.bashrc

日常操作

sops -d ~/.openclaw/secrets.enc.json   # 解密查看
sops ~/.openclaw/secrets.enc.json       # 编辑（自动重加密）

安全等级对比

对 Jay 的建议：单机 VPS 用 env 最简单，一行搞定。如果以后多机器或多环境，迁移到 sops。

评分