OpenClaw 集成 KMS 凭据管家

步骤一：购买和启用 KMS 实例

1. 登录密钥管理服务控制台，在顶部菜单栏选择地域后，在左侧导航栏单击资源 > 实例管理。

2. 在实例管理页面单击创建实例，参考如下配置，选择要购买的 KMS 实例规格，单击立即购买。

   • 密钥管理类型：选择软件密钥管理或硬件密钥管理。

   • 凭据数量：根据业务需求规划，例如100。

3. 购买完成后，返回实例管理页面，在软件密钥管理或硬件密钥管理页面页签，定位到目标 KMS 软件密钥管理实例，单击操作列的启用。

步骤二：创建 KMS 凭据

在 KMS 凭据管家中创建一个凭据，用于存储大模型的 API Key 。

1. 创建密钥

   1. 在顶部菜单栏选择地域后，在左侧导航栏单击资源 > 密钥管理。

   2. 在密钥管理页面，单击用户主密钥页签，实例ID选择软件密钥管理实例，单击创建密钥。

      • 密钥别名：为密钥设置一个易于识别的别名，例如cmk/openclaw/bailiansk。

      • 密钥类型：选择对称密钥。

   说明

   凭据创建完成后，请记录密钥 ARN ，在步骤三中创建 RAM 策略时需要使用，可以在密钥详情页查看这些信息。

2. 创建凭据

   1. 在左侧导航栏单击资源 > 凭据管理

   2. 单击通用凭据页签，选择实例ID后，单击创建凭据，参考如下配置完成各项配置。

      • 凭据名称：输入secret/openclaw/bailiansk。

      • 设置凭据值：粘贴大模型的 API Key ，例如sk-xxxxxxxxxxxxxxxxxxxxxxxx。若何获取百炼 API key ，请参见获取与配置 API Key。

      • 加密主密钥：上一步创建的密钥cmk/openclaw/bailiansk。

   3. 单击确定。

   说明

   凭据创建完成后，请记录凭据的 ARN ，在步骤三中创建 RAM 策略时需要使用，可以在凭据详情页查看这些信息。

步骤三：创建 RAM 角色并授权

创建一个 RAM 角色，授予其获取 KMS 凭据的最小权限，后续将此角色绑定到 ECS 实例。

1. 创建 RAM 权限策略。

   1. 使用阿里云账号（主账号）或拥有 RAM 管理员权限（AliyunRAMFullAccess）的 RAM 用户登录RAM 控制台。

   2. 在左侧导航栏，选择权限管理>权限策略。

   3. 单击创建权限策略，切换到JSON编辑模式，输入以下策略内容。

      {
          "Version": "1",
          "Statement": [
              {
                  "Action": [
                      "kms:GetSecretValue"
                  ],
                  "Resource": "acs:kms:<region>:<account-id>:secret/secret/openclaw/bailiansk",/*凭据的 ARN*/
                  "Effect": "Allow"
              },
              {
                  "Action": [
                      "kms:Decrypt"
                  ],
                  "Resource": "acs:kms:<region>:<account-id>:key/key-hkk69a823******",/*密钥的 ARN*/
                  "Effect": "Allow"
              }
          ]
      }

      说明

      其中 <account-id> 为阿里云账号 ID ，可在控制台账号设置中获取。

      重要

      凭据的 ARN 和密钥的 ARN ，填写步骤二中创建的密钥和凭据详情页获取。

2. 创建 RAM 角色并绑定权限策略。

   1. 在左侧导航栏，选择身份管理>角色。

   2. 单击创建角色，信任主体类型选择阿里云服务，信任主体名称选择云服务器 ECS。

   3. 在权限管理页签，选择上一步创建的权限策略并绑定到该角色。

步骤四：创建 ECS 实例并绑定 RAM 角色

1. 购买一台 ECS 实例，具体操作，请参见快速购买实例。

2. 为 ECS 实例绑定步骤三中创建的 RAM 角色。

   1. 访问ECS控制台-实例。在页面左侧顶部，选择目标资源所在的资源组和地域。

   2. 单击目标 ECS 实例 ID ，在实例详情页单击全部操作，选择实例设置 > 授予/收回RAM角色。

   3. 在对话框中，操作类型选择授予，然后选择步骤三创建的RAM 角色，单击确定。

步骤五：安装 kmscli 命令

kmscli 是一个轻量级命令行工具，使用 ECS 实例 RAM 角色作为默认凭证，从 KMS 凭据管家动态获取凭据值并输出到标准输出。 OpenClaw 启动时将调用此工具来获取敏感的 API Key ，从而避免在配置文件中存储明文。

1. 下载二进制文件

   根据 ECS 操作系统架构，下载对应的 kmscli 二进制文件。以下以最常见的 Linux AMD64 架构为例：

   # 在本地机器或直接在 ECS 上执行
   curl -L -o kmscli-linux-amd64 "https://github.com/aliyun/alibabacloud-kms-cli/releases/latest/download/kmscli-linux-amd64"

   说明

   • 如果使用的是 ARM 架构（如倚天实例），请下载 kmscli-linux-arm64。

   • 如果使用的是 macOS ，请下载 kmscli-darwin-amd64 或 kmscli-darwin-arm64。

   • 完整版本列表请访问 GitHub Releases。

2. 上传至目标目录

   将下载好的文件上传到 ECS 服务器的 ~/.openclaw/ 目录，并重新命名为 kmscli。

   • 本地下载后上传：

     # 在本地终端执行（请替换 user 和 ecs-ip ）
     scp kmscli-linux-amd64 user@<ecs-ip>:~/.openclaw/kmscli

   • 在 ECS 上下载：

     # 在 ECS 终端执行
     cp kmscli-linux-amd64 ~/.openclaw/kmscli

3. 赋予执行权限

   # 登录 ECS 后执行 设置权限（ Linux/macOS ）
   sudo chown $(id -u):$(id -g) ~/.openclaw/kmscli
   chmod +x ~/.openclaw/kmscli

4. 验证权限

   执行以下命令确认文件已就位且具备执行权限：

   ls -l ~/.openclaw/kmscli
   # 预期输出应包含 "-rwxr-xr-x" 权限标识，例如：-rwxr-xr-x 1 admin admin ... kmscli

步骤六：在 ECS 上部署 OpenClaw 并修改配置

1. 按照 OpenClaw 官方文档或OpenClaw 部署流程完成部署。

2. 部署完成后，修改 OpenClaw 配置文件，将明文 API Key 替换为 KMS 凭据引用。

   1. 进入 OpenClaw 安装目录，备份原配置文件。

      cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

   2. 编辑openclaw.json，添加secrets配置，并将apiKey字段的明文值替换为 Secret 引用。配置参考如下。

      • 添加 secrets 配置（在根节点下）：

        {
          "secrets": {
            "providers": {
              "kms_bailian": {
                "source": "exec",
                "command": "/home/用户名/.openclaw/kmscli",
                "args": ["openclaw", "getsecret"],
                "jsonOnly": true
              }
            }
          },
          "models": { ... }
        }

      • 修改 apiKey 配置（在 models.providers 下）：

        {
          "models": {
            "providers": {
              "dashscope": {
                "apiKey": {
                  "source": "exec",
                  "provider": "kms_bailian",
                  "id": "<secret-name>"
                }
              }
            }
          }
        }

3. 配置审计和重新加载secrets配置。

   # 审计配置
   openclaw secrets audit --check
   # 重新加载配置
   openclaw secrets reload