การจัดการข้อมูลลับ

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.

​

เป้าหมายและโมเดลรันไทม์

• การแปลงทำแบบทันทีระหว่างการเปิดใช้งาน ไม่ใช่แบบรอใช้จริงบนเส้นทางคำขอ
• การเริ่มต้นล้มเหลวทันทีเมื่อ SecretRef ที่มีผลใช้งานไม่สามารถแปลงได้
• การโหลดใหม่ใช้การสลับแบบ atomic: สำเร็จทั้งหมด หรือคงสแนปช็อตล่าสุดที่ทราบว่าใช้งานได้ไว้
• การละเมิดนโยบาย SecretRef (เช่น โปรไฟล์ auth โหมด OAuth ที่ใช้ร่วมกับอินพุต SecretRef) จะทำให้การเปิดใช้งานล้มเหลวก่อนสลับรันไทม์
• คำขอรันไทม์อ่านจากสแนปช็อตในหน่วยความจำที่ใช้งานอยู่เท่านั้น
• หลังจากการเปิดใช้งาน/โหลดการกำหนดค่าสำเร็จครั้งแรก เส้นทางโค้ดรันไทม์จะอ่านสแนปช็อตในหน่วยความจำที่ใช้งานอยู่นั้นต่อไป จนกว่าการโหลดใหม่สำเร็จจะสลับสแนปช็อต
• เส้นทางการส่งออกก็อ่านจากสแนปช็อตที่ใช้งานอยู่นั้นเช่นกัน (เช่น การส่งการตอบกลับ/เธรดของ Discord และการส่งแอ็กชันของ Telegram); เส้นทางเหล่านี้จะไม่แปลง SecretRefs ใหม่ในทุกการส่ง

​

การกรองพื้นผิวที่ใช้งานอยู่

• พื้นผิวที่เปิดใช้งาน: refs ที่ยังไม่ได้แปลงจะบล็อกการเริ่มต้น/การโหลดใหม่
• พื้นผิวที่ไม่ใช้งาน: refs ที่ยังไม่ได้แปลงจะไม่บล็อกการเริ่มต้น/การโหลดใหม่
• refs ที่ไม่ใช้งานจะส่ง diagnostics แบบไม่ร้ายแรงพร้อมรหัส SECRETS_REF_IGNORED_INACTIVE_SURFACE

​

diagnostics ของพื้นผิว auth ของ Gateway

• active: SecretRef เป็นส่วนหนึ่งของพื้นผิว auth ที่มีผลและต้องแปลงได้
• inactive: SecretRef ถูกละเว้นสำหรับรันไทม์นี้ เพราะพื้นผิว auth อื่นชนะ หรือเพราะ remote auth ถูกปิดใช้งาน/ไม่ได้ใช้งาน

​

preflight การอ้างอิงระหว่าง onboarding

• Env refs: ตรวจสอบชื่อ env var และยืนยันว่ามีค่าที่ไม่ว่างมองเห็นได้ระหว่างการตั้งค่า
• Provider refs (file หรือ exec): ตรวจสอบการเลือกผู้ให้บริการ แปลง id และตรวจชนิดของค่าที่แปลงได้
• เส้นทางใช้ซ้ำ Quickstart: เมื่อ gateway.auth.token เป็น SecretRef อยู่แล้ว onboarding จะแปลงค่าก่อน probe/dashboard bootstrap (สำหรับ refs แบบ env, file และ exec) โดยใช้เกต fail-fast เดียวกัน

​

สัญญา 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" }

​

การกำหนดค่าผู้ให้บริการ

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

​

ตัวอย่างการผสาน Exec

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

​

ตัวแปรสภาพแวดล้อมของเซิร์ฟเวอร์ 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",
                },
              },
            },
          },
        },
      },
    },
  },
}

​

วัสดุ auth สำหรับ SSH ของ sandbox

{
  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 แก้ค่า refs เหล่านี้ระหว่างการเปิดใช้งาน sandbox ไม่ใช่แบบ lazy ระหว่างการเรียก SSH แต่ละครั้ง
• ค่าที่แก้แล้วจะถูกเขียนลงไฟล์ชั่วคราวด้วยสิทธิ์ที่จำกัด และใช้ในคอนฟิก SSH ที่สร้างขึ้น
• หาก backend ของ sandbox ที่มีผลไม่ใช่ ssh refs เหล่านี้จะยังไม่ทำงานและไม่บล็อกการเริ่มต้นระบบ

​

พื้นผิวข้อมูลประจำตัวที่รองรับ

• พื้นผิวข้อมูลประจำตัวของ SecretRef

​

พฤติกรรมและลำดับความสำคัญที่ต้องมี

• ฟิลด์ที่ไม่มี ref: ไม่เปลี่ยนแปลง
• ฟิลด์ที่มี ref: จำเป็นต้องมีบนพื้นผิวที่ใช้งานอยู่ระหว่างการเปิดใช้งาน
• หากมีทั้ง plaintext และ ref อยู่พร้อมกัน ref จะมีลำดับความสำคัญเหนือกว่าในเส้นทางลำดับความสำคัญที่รองรับ
• ตัวบ่งชี้การปกปิด __OPENCLAW_REDACTED__ ถูกสงวนไว้สำหรับการปกปิด/กู้คืนคอนฟิกภายใน และจะถูกปฏิเสธหากส่งมาเป็นข้อมูลคอนฟิก literal

• SECRETS_REF_OVERRIDES_PLAINTEXT (คำเตือน runtime)
• REF_SHADOWED (ผลการ audit เมื่อข้อมูลประจำตัวใน auth-profiles.json มีลำดับความสำคัญเหนือ refs ใน openclaw.json)

• serviceAccountRef มีลำดับความสำคัญเหนือ plaintext serviceAccount
• ค่า plaintext จะถูกละเว้นเมื่อมี sibling ref ตั้งค่าไว้

​

ตัวกระตุ้นการเปิดใช้งาน

• เริ่มต้นระบบ (preflight และการเปิดใช้งานขั้นสุดท้าย)
• เส้นทาง hot-apply ของการ reload คอนฟิก
• เส้นทาง restart-check ของการ reload คอนฟิก
• reload ด้วยตนเองผ่าน secrets.reload
• preflight ของ Gateway config write RPC (config.set / config.apply / config.patch) เพื่อตรวจสอบว่า SecretRef บนพื้นผิวที่ใช้งานอยู่สามารถแก้ค่าได้ภายใน payload คอนฟิกที่ส่งมา ก่อนบันทึกการแก้ไข

• เมื่อสำเร็จ จะสลับ snapshot แบบ atomic
• การเริ่มต้นระบบล้มเหลวจะยกเลิกการเริ่มต้น Gateway
• การ reload ระหว่าง runtime ล้มเหลวจะคง snapshot ล่าสุดที่ทราบว่าใช้งานได้ดีไว้
• preflight ของ Write-RPC ล้มเหลวจะปฏิเสธคอนฟิกที่ส่งมา และคงทั้งคอนฟิกบนดิสก์กับ snapshot runtime ที่ใช้งานอยู่ไว้โดยไม่เปลี่ยนแปลง
• การระบุ channel token แบบต่อการเรียกอย่างชัดเจนให้กับ outbound helper/tool call จะไม่กระตุ้นการเปิดใช้งาน SecretRef; จุดเปิดใช้งานยังคงเป็นการเริ่มต้นระบบ, reload และ secrets.reload อย่างชัดเจน

​

สัญญาณ degraded และ recovered

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• Degraded: runtime จะคง snapshot ล่าสุดที่ทราบว่าใช้งานได้ดีไว้
• Recovered: ส่งออกหนึ่งครั้งหลังการเปิดใช้งานสำเร็จครั้งถัดไป
• ความล้มเหลวซ้ำขณะอยู่ในสถานะ degraded อยู่แล้วจะ log คำเตือน แต่ไม่ส่ง event ซ้ำมากเกินไป
• การ fail-fast ตอนเริ่มต้นระบบจะไม่ส่ง event degraded เพราะ runtime ยังไม่เคย active

​

การแก้ค่าในเส้นทางคำสั่ง

• การ refresh snapshot หลังจากการหมุน secret ใน backend จัดการด้วย openclaw secrets reload
• เมธอด Gateway RPC ที่เส้นทางคำสั่งเหล่านี้ใช้: secrets.resolve

​

เวิร์กโฟลว์ audit และ configure

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

​

นโยบายความปลอดภัยแบบทางเดียว

• preflight ต้องสำเร็จก่อนโหมดเขียน
• การเปิดใช้งาน runtime จะถูกตรวจสอบก่อน commit
• apply อัปเดตไฟล์ด้วยการแทนที่ไฟล์แบบ atomic และพยายาม restore ให้ดีที่สุดเมื่อเกิดความล้มเหลว

​

หมายเหตุความเข้ากันได้ของ auth legacy

• แหล่งข้อมูลประจำตัวของ runtime คือ snapshot ในหน่วยความจำที่แก้ค่าแล้ว
• รายการ api_key แบบ static legacy จะถูกล้างเมื่อพบ
• พฤติกรรมความเข้ากันได้ที่เกี่ยวกับ OAuth ยังคงแยกต่างหาก

​

หมายเหตุ Web UI

​

ที่เกี่ยวข้อง

• การยืนยันตัวตน — การตั้งค่า auth
• CLI: secrets — คำสั่ง CLI
• ตัวแปรสภาพแวดล้อม — ลำดับความสำคัญของสภาพแวดล้อม
• พื้นผิวข้อมูลประจำตัวของ SecretRef — พื้นผิวข้อมูลประจำตัว
• สัญญาแผน Secrets Apply — รายละเอียดสัญญาของแผน
• ความปลอดภัย — ท่าทีด้านความปลอดภัย