Quản lý bí mật

OpenClaw hỗ trợ SecretRefs bổ sung để các thông tin xác thực được hỗ trợ không cần được lưu dưới dạng văn bản thuần trong cấu hình.

# Mục tiêu và mô hình thời gian chạy

Secrets được phân giải vào một ảnh chụp nhanh thời gian chạy trong bộ nhớ.

• Việc phân giải diễn ra chủ động trong quá trình kích hoạt, không trì hoãn trên các đường dẫn yêu cầu.
• Khởi động thất bại sớm khi một SecretRef thực sự hoạt động không thể được phân giải.
• Tải lại dùng hoán đổi nguyên tử: thành công hoàn toàn, hoặc giữ ảnh chụp nhanh tốt đã biết gần nhất.
• Vi phạm chính sách SecretRef (ví dụ hồ sơ xác thực ở chế độ OAuth kết hợp với đầu vào SecretRef) làm kích hoạt thất bại trước khi hoán đổi thời gian chạy.
• Yêu cầu thời gian chạy chỉ đọc từ ảnh chụp nhanh trong bộ nhớ đang hoạt động.
• Sau lần kích hoạt/tải cấu hình thành công đầu tiên, các đường dẫn mã thời gian chạy tiếp tục đọc ảnh chụp nhanh trong bộ nhớ đang hoạt động đó cho đến khi một lần tải lại thành công hoán đổi nó.
• Các đường dẫn gửi đi cũng đọc từ ảnh chụp nhanh đang hoạt động đó (ví dụ gửi trả lời/luồng Discord và gửi hành động Telegram); chúng không phân giải lại SecretRefs trên mỗi lần gửi.

Điều này giữ các sự cố ngừng hoạt động của nhà cung cấp secret khỏi các đường dẫn yêu cầu nóng.

# Lọc bề mặt hoạt động

SecretRefs chỉ được xác thực trên các bề mặt thực sự hoạt động.

• Bề mặt đã bật: tham chiếu chưa phân giải chặn khởi động/tải lại.
• Bề mặt không hoạt động: tham chiếu chưa phân giải không chặn khởi động/tải lại.
• Tham chiếu không hoạt động phát ra chẩn đoán không gây lỗi với mã SECRETS_REF_IGNORED_INACTIVE_SURFACE.

# Chẩn đoán bề mặt xác thực Gateway

Khi một SecretRef được cấu hình trên gateway.auth.token, gateway.auth.password, gateway.remote.token, hoặc gateway.remote.password, khởi động/tải lại Gateway ghi nhật ký trạng thái bề mặt một cách rõ ràng:

• active: SecretRef là một phần của bề mặt xác thực hiệu dụng và phải phân giải được.
• inactive: SecretRef bị bỏ qua cho thời gian chạy này vì một bề mặt xác thực khác thắng, hoặc vì xác thực từ xa bị tắt/không hoạt động.

Các mục này được ghi nhật ký với SECRETS_GATEWAY_AUTH_SURFACE và bao gồm lý do được chính sách bề mặt hoạt động sử dụng, để bạn có thể thấy vì sao một thông tin xác thực được coi là hoạt động hoặc không hoạt động.

# Kiểm tra sơ bộ tham chiếu khi thiết lập ban đầu

Khi thiết lập ban đầu chạy ở chế độ tương tác và bạn chọn lưu trữ SecretRef, OpenClaw chạy xác thực sơ bộ trước khi lưu:

• Tham chiếu biến môi trường: xác thực tên biến môi trường và xác nhận có thể thấy một giá trị không rỗng trong quá trình thiết lập.
• Tham chiếu nhà cung cấp (file hoặc exec): xác thực lựa chọn nhà cung cấp, phân giải id, và kiểm tra kiểu giá trị đã phân giải.
• Đường dẫn tái sử dụng khởi động nhanh: khi gateway.auth.token đã là một SecretRef, thiết lập ban đầu phân giải nó trước khi khởi động probe/dashboard (cho tham chiếu env, file, và exec) bằng cùng cổng thất bại sớm.

Nếu xác thực thất bại, thiết lập ban đầu hiển thị lỗi và cho phép bạn thử lại.

# Hợp đồng SecretRef

Dùng một dạng đối tượng ở mọi nơi:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

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

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

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

# Cấu hình nhà cung cấp

Định nghĩa nhà cung cấp dưới secrets.providers:

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

# Ví dụ tích hợp thực thi

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

# Biến môi trường máy chủ MCP

Các biến môi trường máy chủ MCP được cấu hình qua plugins.entries.acpx.config.mcpServers hỗ trợ SecretInput. Điều này giữ khóa API và token không nằm trong cấu hình văn bản thuần:

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

Giá trị chuỗi văn bản thuần vẫn hoạt động. Tham chiếu mẫu biến môi trường như ${MCP_SERVER_API_KEY} và đối tượng SecretRef được phân giải trong quá trình kích hoạt Gateway trước khi tiến trình máy chủ MCP được sinh ra. Như với các bề mặt SecretRef khác, tham chiếu chưa phân giải chỉ chặn kích hoạt khi Plugin acpx thực sự hoạt động.

# Dữ liệu xác thực SSH cho môi trường cách ly

Phần phụ trợ môi trường cách ly lõi ssh cũng hỗ trợ SecretRefs cho dữ liệu xác thực SSH:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        ssh: {
          target: "user@gateway-host:22",
          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

Hành vi thời gian chạy:

• OpenClaw phân giải các tham chiếu này trong khi kích hoạt sandbox, không phân giải lười trong từng lệnh gọi SSH.
• Các giá trị đã phân giải được ghi vào tệp tạm với quyền hạn chế và được dùng trong cấu hình SSH đã tạo.
• Nếu backend sandbox hiệu lực không phải là ssh, các tham chiếu này vẫn không hoạt động và không chặn khởi động.

# Bề mặt thông tin xác thực được hỗ trợ

Thông tin xác thực được hỗ trợ và không được hỗ trợ chính thức được liệt kê tại:

• Bề mặt thông tin xác thực SecretRef

# Hành vi bắt buộc và thứ tự ưu tiên

• Trường không có tham chiếu: không đổi.
• Trường có tham chiếu: bắt buộc trên các bề mặt đang hoạt động trong khi kích hoạt.
• Nếu có cả văn bản thuần và tham chiếu, tham chiếu được ưu tiên trên các đường dẫn ưu tiên được hỗ trợ.
• Chỉ báo biên tập lại __OPENCLAW_REDACTED__ được dành riêng cho biên tập lại/khôi phục cấu hình nội bộ và bị từ chối nếu được gửi làm dữ liệu cấu hình dạng literal.

Tín hiệu cảnh báo và kiểm toán:

• SECRETS_REF_OVERRIDES_PLAINTEXT (cảnh báo thời gian chạy)
• REF_SHADOWED (phát hiện kiểm toán khi thông tin xác thực trong auth-profiles.json được ưu tiên hơn tham chiếu trong openclaw.json)

Hành vi tương thích Google Chat:

• serviceAccountRef được ưu tiên hơn serviceAccount dạng văn bản thuần.
• Giá trị văn bản thuần bị bỏ qua khi tham chiếu cùng cấp được đặt.

# Bộ kích hoạt kích hoạt

Kích hoạt bí mật chạy khi:

• Khởi động (kiểm tra trước cộng với kích hoạt cuối cùng)
• Đường dẫn áp dụng nóng khi tải lại cấu hình
• Đường dẫn kiểm tra khởi động lại khi tải lại cấu hình
• Tải lại thủ công qua secrets.reload
• Kiểm tra trước RPC ghi cấu hình Gateway (config.set / config.apply / config.patch) để đảm bảo SecretRef trên bề mặt hoạt động có thể phân giải trong tải trọng cấu hình đã gửi trước khi lưu các chỉnh sửa

Hợp đồng kích hoạt:

• Thành công sẽ hoán đổi snapshot một cách nguyên tử.
• Lỗi khởi động sẽ hủy khởi động gateway.
• Lỗi tải lại trong thời gian chạy giữ snapshot tốt đã biết gần nhất.
• Lỗi kiểm tra trước write-RPC từ chối cấu hình đã gửi và giữ nguyên cả cấu hình trên đĩa lẫn snapshot thời gian chạy đang hoạt động.
• Việc cung cấp token kênh theo từng lệnh gọi rõ ràng cho một lệnh gọi helper/công cụ gửi đi không kích hoạt SecretRef; các điểm kích hoạt vẫn là khởi động, tải lại và secrets.reload rõ ràng.

# Tín hiệu suy giảm và phục hồi

Khi kích hoạt lúc tải lại thất bại sau một trạng thái khỏe mạnh, OpenClaw đi vào trạng thái bí mật suy giảm.

Sự kiện hệ thống một lần và mã nhật ký:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Hành vi:

• Suy giảm: thời gian chạy giữ snapshot tốt đã biết gần nhất.
• Phục hồi: được phát một lần sau lần kích hoạt thành công tiếp theo.
• Các lỗi lặp lại khi đã suy giảm sẽ ghi cảnh báo nhưng không gửi sự kiện dồn dập.
• Khởi động thất bại nhanh không phát sự kiện suy giảm vì thời gian chạy chưa từng trở nên hoạt động.

# Phân giải đường dẫn lệnh

Đường dẫn lệnh có thể chọn dùng cơ chế phân giải SecretRef được hỗ trợ qua RPC snapshot gateway.

Có hai nhóm hành vi rộng:

Ghi chú khác:

• Làm mới snapshot sau khi bí mật backend xoay vòng được xử lý bằng openclaw secrets reload.
• Phương thức RPC Gateway được các đường dẫn lệnh này dùng: secrets.resolve.

# Quy trình kiểm toán và cấu hình

Luồng mặc định cho toán tử:

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

# Chính sách an toàn một chiều

Mô hình an toàn:

• kiểm tra trước phải thành công trước chế độ ghi
• kích hoạt thời gian chạy được xác thực trước khi commit
• apply cập nhật tệp bằng thay thế tệp nguyên tử và khôi phục nỗ lực tối đa khi thất bại

# Ghi chú tương thích xác thực cũ

Đối với thông tin xác thực tĩnh, thời gian chạy không còn phụ thuộc vào lưu trữ xác thực cũ dạng văn bản thuần.

• Nguồn thông tin xác thực thời gian chạy là snapshot trong bộ nhớ đã phân giải.
• Các mục api_key tĩnh cũ được loại bỏ khi được phát hiện.
• Hành vi tương thích liên quan đến OAuth vẫn tách biệt.

# Ghi chú giao diện web

Một số union SecretInput dễ cấu hình trong chế độ trình chỉnh sửa thô hơn chế độ biểu mẫu.

# Liên quan

• Xác thực — thiết lập xác thực
• CLI: secrets — lệnh CLI
• Biến môi trường — thứ tự ưu tiên môi trường
• Bề mặt thông tin xác thực SecretRef — bề mặt thông tin xác thực
• Hợp đồng kế hoạch áp dụng bí mật — chi tiết hợp đồng kế hoạch
• Bảo mật — tư thế bảo mật