Quản lý bí mật

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

• 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.

​

Lọc bề mặt 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

• 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.

​

Kiểm tra sơ bộ tham chiếu khi thiết lập ban đầ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.

​

Hợp đồng SecretRef

{ 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

{
  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

{
  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",
                },
              },
            },
          },
        },
      },
    },
  },
}

​

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

{
  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" },
        },
      },
    },
  },
}

• 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ợ

• 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.

• 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)

• 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

• 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

• 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

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• 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

• 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

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

• 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ũ

• 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

​

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