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

OpenClaw รองรับ SecretRefs แบบเพิ่มต่อได้ เพื่อไม่ให้ข้อมูลรับรองที่รองรับต้องจัดเก็บเป็นข้อความธรรมดาในการกำหนดค่า

โมเดลรันไทม์

• ซีเคร็ตจะถูกแก้ค่าเป็นสแนปช็อตรันไทม์ในหน่วยความจำล่วงหน้าระหว่างการเปิดใช้งาน ไม่ใช่แบบหน่วงเวลาในเส้นทางคำขอ
• การเริ่มต้น Gateway แบบ cold จะแยกความล้มเหลวของ SecretRef ที่ลองใหม่ได้ไปยังเจ้าของที่ทราบแน่ชัดซึ่งไม่ใช่ Gateway เมื่อเจ้าของนั้นรองรับการแยก เจ้าของที่แมปไว้ประกอบด้วยผู้ให้บริการโมเดลและ Skills, ผู้ให้บริการสื่อ/TTS/cron, โปรไฟล์การยืนยันตัวตนที่มีสิทธิ์, หน่วยความจำรายเอเจนต์, sandbox SSH, บัญชีช่องทาง และเส้นทาง Plugin ที่ประกาศใน manifest Gateway จะเริ่มทำงาน บันทึกเจ้าของว่าได้รับการกำหนดค่าแต่ใช้งานไม่ได้ และแสดงคำเตือนการลดระดับการทำงานที่ปกปิดข้อมูลแล้ว การยืนยันตัวตนขาเข้าของ Gateway, การอ้างอิงหรือค่าที่แก้แล้วซึ่งมีโครงสร้างไม่ถูกต้อง, เจ้าของที่ต้องล้มเหลวแบบปิด และการอ้างอิงที่ไม่ได้แมปเจ้าของรันไทม์ ยังคงทำให้การเริ่มต้นล้มเหลว
• การโหลดใหม่จะตรวจสอบเจ้าของแต่ละรายที่แมปไว้อย่างเป็นอิสระ จากนั้นเผยแพร่สแนปช็อตเดียวแบบอะตอมมิก เจ้าของที่ปกติจะได้รับการรีเฟรช เจ้าของที่มีสิทธิ์แต่ล้มเหลวจะเก็บค่าล่าสุดที่ทราบว่าใช้งานได้ และจะกลายเป็น stale เฉพาะเมื่ออัตลักษณ์ของการอ้างอิง นิยามผู้ให้บริการ และสัญญาเจ้าของส่วนที่ไม่ใช่ซีเคร็ตทั้งหมดไม่เปลี่ยนแปลง ส่วนเจ้าของที่เปลี่ยนแปลงหรือเพิ่มใหม่และล้มเหลวจะกลายเป็น cold ความล้มเหลวแบบเข้มงวดจะปฏิเสธการโหลดใหม่และคงสแนปช็อตที่ใช้งานอยู่ไว้
• การละเมิดนโยบาย (เช่น โปรไฟล์การยืนยันตัวตนโหมด OAuth ที่ใช้ร่วมกับอินพุต SecretRef) จะทำให้การเปิดใช้งานล้มเหลวก่อนสลับรันไทม์
• คำขอรันไทม์จะอ่านเฉพาะสแนปช็อตในหน่วยความจำที่ใช้งานอยู่ ข้อมูลรับรอง SecretRef ของผู้ให้บริการโมเดลจะผ่านพื้นที่จัดเก็บการยืนยันตัวตนและตัวเลือกสตรีมในรูป sentinel ภายในโปรเซสจนถึงขาออก เส้นทางการนำส่งขาออก (การนำส่งการตอบกลับ/เธรดของ Discord, การส่งการดำเนินการของ Telegram) จะอ่านสแนปช็อตนั้นเช่นกัน และจะไม่แก้ค่าการอ้างอิงใหม่ในการส่งแต่ละครั้ง

แนวทางนี้ทำให้เหตุขัดข้องของผู้ให้บริการซีเคร็ตไม่กระทบเส้นทางคำขอที่ใช้งานหนัก

การป้องกันขาเข้าของ Gateway, การกำหนดค่าหรือค่าที่แก้แล้วซึ่งมีโครงสร้างไม่ถูกต้อง, การละเมิดนโยบาย และเจ้าของที่ไม่ทราบแน่ชัด ยังคงล้มเหลวแบบปิด เจ้าของที่ถูกแยกจะไม่ย้อนกลับไปใช้แหล่งข้อมูลรับรองที่มีลำดับความสำคัญต่ำกว่า

การแทรกค่าขณะส่งออก (sentinel)

สำหรับข้อมูลรับรองของผู้ให้บริการโมเดลที่ใช้ SecretRefs เป็นแหล่งข้อมูล OpenClaw จะสร้าง sentinel แบบทึบซึ่งใช้ได้เฉพาะภายในโปรเซส ระหว่างการแก้ค่าการยืนยันตัวตนของโมเดล ดังนั้นพื้นที่จัดเก็บการยืนยันตัวตน ตัวเลือกสตรีม การกำหนดค่า SDK บันทึก ออบเจ็กต์ข้อผิดพลาด และการตรวจสอบรันไทม์ส่วนใหญ่จะเห็นค่าอย่างเช่น oc-sent-v1-... แทนข้อมูลรับรองของผู้ให้บริการ การดึงข้อมูลโมเดลที่มีการป้องกันและโพรบตรวจสอบสถานะผู้ให้บริการภายในเครื่องที่มีการจัดการ จะแทนที่ sentinel ที่ทราบในค่า URL และส่วนหัวทันทีก่อนที่แต่ละคำขอจะออกจากโปรเซส

ค่าที่มีรูปแบบเหมือน sentinel แต่ไม่เป็นที่รู้จักจะล้มเหลวแบบปิดก่อนเกิดกิจกรรมเครือข่าย OpenClaw จะปฏิเสธการส่งคำขอแทนการส่งต่อ sentinel ที่ยังไม่ได้แก้ค่าไปยังผู้ให้บริการ ค่าซีเคร็ตที่แก้แล้วจะได้รับการลงทะเบียนเพื่อปกปิดค่าที่ตรงกันทุกประการในบันทึกด้วย เพื่อเป็นมาตรการป้องกันหลายชั้น

อะแดปเตอร์ของผู้ให้บริการใช้จุดแทรกค่าที่ช้าที่สุดซึ่ง SDK รองรับ:

• SDK ที่มีตัวเลือก fetch แบบกำหนดเองจะได้รับ fetch ที่มีการป้องกันของ OpenClaw เพื่อให้ SDK ยังคงเก็บ sentinel ไว้
• SDK ที่ไม่มีตัวเลือก fetch แบบกำหนดเองจะแกะ sentinel ทันทีก่อนสร้างไคลเอนต์ สตรีมผู้ให้บริการที่ Plugin เป็นเจ้าของและชุดควบคุมเอเจนต์จะแกะค่าที่จุดส่งต่อสุดท้ายซึ่ง core เป็นเจ้าของ เนื่องจากการขนส่งเหล่านั้นไม่ได้ใช้ fetch ที่มีการป้องกันของ OpenClaw ร่วมกัน

Sentinel ลดการเปิดเผยข้อความธรรมดาตลอดสายการเรียกโมเดล แต่ไม่ใช่การแยกโปรเซส ค่าจริงยังคงอยู่ในหน่วยความจำของโปรเซสเดียวกันและปรากฏที่ขอบเขตอะแดปเตอร์สุดท้าย ข้อมูลรับรองจากสภาพแวดล้อมแบบธรรมดาที่ไม่ได้กำหนดค่าผ่าน SecretRefs ยังคงเป็นข้อความธรรมดาและอยู่นอกกลไกนี้

ตั้งค่า OPENCLAW_SECRET_SENTINELS=off (รองรับ 0 หรือ false ด้วย โดยไม่คำนึงถึงตัวพิมพ์เล็ก-ใหญ่) เพื่อปิดการสร้าง sentinel ระหว่างการตอบสนองต่อเหตุการณ์หรือการแก้ไขปัญหาความเข้ากันได้ สวิตช์หยุดฉุกเฉินนี้จะไม่ปิดการลงทะเบียนการปกปิดค่าที่ตรงกันทุกประการ

ขอบเขตการเข้าถึงของเอเจนต์

SecretRefs ป้องกันไม่ให้ข้อมูลรับรองถูกบันทึกถาวรในการกำหนดค่าและไฟล์โมเดลที่สร้างขึ้น แต่ไม่ใช่ขอบเขตการแยกโปรเซส ข้อมูลรับรองแบบข้อความธรรมดาที่หลงเหลืออยู่บนดิสก์ในพาธที่เอเจนต์อ่านได้ ยังคงอ่านได้ผ่านเครื่องมือไฟล์หรือเชลล์ โดยข้ามการปกปิดระดับ API

สำหรับการใช้งานจริงที่ไฟล์ซึ่งเอเจนต์เข้าถึงได้อยู่ในขอบเขต ให้ถือว่าการย้ายเสร็จสมบูรณ์ก็ต่อเมื่อเป็นไปตามเงื่อนไขทั้งหมดต่อไปนี้:

• ข้อมูลรับรองที่รองรับใช้ SecretRefs แทนค่าข้อความธรรมดา
• ล้างข้อความธรรมดาแบบเก่าที่ตกค้างออกจาก openclaw.json, auth-profiles.json, .env และไฟล์ models.json ที่สร้างขึ้นแล้ว
• openclaw secrets audit --check ไม่มีสิ่งตกค้างหลังการย้าย
• ข้อมูลรับรองที่เหลือซึ่งยังไม่รองรับหรือมีการหมุนเวียน ต้องได้รับการป้องกันด้วยการแยกระดับระบบปฏิบัติการ การแยกคอนเทนเนอร์ หรือพร็อกซีข้อมูลรับรองภายนอก

นี่คือเหตุผลที่เวิร์กโฟลว์ตรวจสอบ/กำหนดค่า/นำไปใช้เป็นเกตการย้ายด้านความปลอดภัย ไม่ใช่เพียงตัวช่วยอำนวยความสะดวก

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

SecretRefs จะได้รับการตรวจสอบเฉพาะบนพื้นผิวที่มีผลใช้งานจริง:

• พื้นผิวที่เปิดใช้: ความล้มเหลวที่ลองใหม่ได้สำหรับเจ้าของที่แมปและแยกได้ จะเข้าสู่สถานะลดระดับแบบ cold หรือ stale ความล้มเหลวแบบเข้มงวด แบบล้มเหลวปิด ที่ Gateway จำเป็นต้องใช้ หรือที่ไม่ได้แมป จะบล็อกการเริ่มต้น/โหลดใหม่
• พื้นผิวที่ไม่ใช้งาน: การอ้างอิงที่แก้ค่าไม่ได้จะไม่บล็อกการเริ่มต้น/โหลดใหม่ แต่จะแสดงการวินิจฉัย SECRETS_REF_IGNORED_INACTIVE_SURFACE ที่ไม่ทำให้ล้มเหลว

การวินิจฉัยพื้นผิวการยืนยันตัวตนของ Gateway

เมื่อตั้งค่า SecretRef บน gateway.auth.token, gateway.auth.password, gateway.remote.token หรือ gateway.remote.password บันทึกการเริ่มต้น/โหลดใหม่ของ Gateway จะแสดงสถานะพื้นผิวภายใต้รหัส SECRETS_GATEWAY_AUTH_SURFACE:

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

รายการบันทึกจะระบุเหตุผลที่นโยบายพื้นผิวที่ใช้งานอยู่เลือกใช้

การตรวจสอบการอ้างอิงล่วงหน้าระหว่างการเริ่มต้นใช้งาน

ในการเริ่มต้นใช้งานแบบโต้ตอบ การเลือกพื้นที่จัดเก็บ SecretRef จะเรียกใช้การตรวจสอบล่วงหน้าก่อนบันทึก:

• การอ้างอิง Env: ตรวจสอบชื่อของตัวแปรสภาพแวดล้อมและยืนยันว่ามองเห็นค่าที่ไม่ว่างระหว่างการตั้งค่า
• การอ้างอิงผู้ให้บริการ (file หรือ exec): ตรวจสอบการเลือกผู้ให้บริการ แก้ค่า id และตรวจสอบชนิดของค่าที่แก้แล้ว
• ขั้นตอนเริ่มต้นด่วน: เมื่อ gateway.auth.token เป็น SecretRef อยู่แล้ว การเริ่มต้นใช้งานจะแก้ค่าก่อนเริ่มโพรบ/แดชบอร์ด (สำหรับการอ้างอิง env, file และ exec) โดยใช้เกตที่ล้มเหลวทันทีแบบเดียวกัน

หากการตรวจสอบล้มเหลว ระบบจะแสดงข้อผิดพลาดและให้ลองใหม่ได้

สัญญา SecretRef

ใช้รูปแบบออบเจ็กต์เดียวกันทุกที่:

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

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

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

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

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

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

กำหนดผู้ให้บริการภายใต้ secrets.providers:

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // หรือ "singleValue"      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        args: ["--profile", "prod"],        passEnv: ["PATH", "VAULT_ADDR"],        jsonOnly: true,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },  },}

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

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: รายการอนุญาตข้อมูลลับ

{"protocolVersion": 1,"values": {},"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }}

คีย์ API ที่จัดเก็บในไฟล์

อย่าใส่สตริง file:... ในบล็อก env ของการกำหนดค่า บล็อกนั้นเป็นค่าตามตัวอักษรและไม่เขียนทับค่าอื่น ดังนั้น file:... จะไม่ได้รับการแก้ไขค่าในบล็อกนั้น

ให้ใช้ SecretRef แบบไฟล์ในฟิลด์ข้อมูลรับรองที่รองรับแทน:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

สำหรับ mode: "singleValue" ค่า id ของ SecretRef คือ "value" สำหรับ mode: "json" ให้ใช้ตัวชี้ JSON แบบสัมบูรณ์ เช่น "/providers/xai/apiKey"

ดูฟิลด์ที่ยอมรับ SecretRef ได้ที่ พื้นผิวข้อมูลรับรอง SecretRef

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

สำหรับคู่มือ 1Password โดยเฉพาะ ซึ่งครอบคลุมบัญชีบริการ Skills ของเอเจนต์ที่รวมมาให้ และการแก้ไขปัญหา โปรดดู 1Password

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // จำเป็นสำหรับไบนารีที่ Homebrew เชื่อมโยงด้วยลิงก์สัญลักษณ์        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: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // จำเป็นสำหรับไบนารีที่ Homebrew เชื่อมโยงด้วยลิงก์สัญลักษณ์        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" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`แยกวิเคราะห์คำขอไม่สำเร็จ: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass ออกจากการทำงานด้วยสถานะ ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // จำเป็นสำหรับไบนารีที่ Homebrew เชื่อมโยงด้วยลิงก์สัญลักษณ์        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

ตัวแปรสภาพแวดล้อมของเซิร์ฟเวอร์ MCP ที่กำหนดค่าผ่าน plugins.entries.acpx.config.mcpServers ยอมรับ SecretInput ซึ่งช่วยไม่ให้คีย์ API และโทเค็นอยู่ในการกำหนดค่าแบบข้อความธรรมดา:

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

ค่าสตริงแบบข้อความธรรมดายังคงใช้งานได้ การอ้างอิงเทมเพลตตัวแปรสภาพแวดล้อม เช่น ${MCP_SERVER_API_KEY} และออบเจ็กต์ SecretRef จะได้รับการแก้ไขค่าระหว่างการเปิดใช้งาน Gateway ก่อนเริ่มกระบวนการเซิร์ฟเวอร์ MCP เช่นเดียวกับพื้นผิว SecretRef อื่น การอ้างอิงที่แก้ไขค่าไม่ได้จะขัดขวางการเปิดใช้งานเฉพาะเมื่อ Plugin acpx มีสถานะใช้งานจริงเท่านั้น

ข้อมูลยืนยันตัวตน SSH สำหรับ Sandbox

แบ็กเอนด์ Sandbox หลัก ssh รองรับ SecretRef สำหรับข้อมูลยืนยันตัวตน 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" },        },      },    },  },}

พฤติกรรมขณะรันไทม์:

• OpenClaw แก้ไขการอ้างอิงเหล่านี้ระหว่างการเปิดใช้งานแซนด์บ็อกซ์ ไม่ใช่แบบหน่วงเวลาในแต่ละครั้งที่เรียกใช้ SSH
• ค่าที่แก้ไขแล้วจะถูกเขียนลงในไดเรกทอรีชั่วคราวโดยมีสิทธิ์เข้าถึงไฟล์ที่เข้มงวด (0o600) และใช้ในคอนฟิก SSH ที่สร้างขึ้น
• หากแบ็กเอนด์แซนด์บ็อกซ์ที่มีผลไม่ใช่ ssh (หรือโหมดแซนด์บ็อกซ์เป็น off) การอ้างอิงเหล่านี้จะยังไม่ทำงานและไม่ขัดขวางการเริ่มต้นระบบ

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

ข้อมูลประจำตัวที่รองรับและไม่รองรับตามมาตรฐานแสดงอยู่ใน พื้นผิวข้อมูลประจำตัว SecretRef

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

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

สัญญาณคำเตือนและการตรวจสอบ:

• SECRETS_REF_OVERRIDES_PLAINTEXT (คำเตือนขณะรันไทม์)
• REF_SHADOWED (ข้อค้นพบจากการตรวจสอบเมื่อข้อมูลประจำตัว auth-profiles.json มีลำดับความสำคัญเหนือการอ้างอิง openclaw.json)

ความเข้ากันได้กับ Google Chat: serviceAccountRef มีลำดับความสำคัญเหนือข้อความธรรมดา serviceAccount; ค่าข้อความธรรมดาจะถูกละเว้นเมื่อตั้งค่าการอ้างอิงระดับเดียวกันแล้ว

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

การเปิดใช้งานข้อมูลลับจะทำงานเมื่อ:

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

สัญญาการเปิดใช้งาน:

• เมื่อสำเร็จ ระบบจะสลับสแนปช็อตแบบอะตอมมิก
• ความล้มเหลวแบบเข้มงวดระหว่างการเริ่มต้นจะยกเลิกการเริ่มต้น Gateway
• ระหว่างการเริ่มต้นแบบเย็น ความล้มเหลวในการแก้ไขที่ลองใหม่ได้สำหรับเจ้าของที่ไม่ใช่ Gateway ซึ่งมีการแมปและแยกได้ อาจเผยแพร่สแนปช็อตโดยตั้งค่าเฉพาะเจ้าของรายนั้นว่าไม่พร้อมใช้งานตามคอนฟิก คำขอสำหรับเจ้าของจะล้มเหลวด้วย SECRET_SURFACE_UNAVAILABLE; เจ้าของผู้ให้บริการโมเดลจะไม่ถอยกลับไปใช้ข้อมูลประจำตัวจากสภาพแวดล้อมหรือโปรไฟล์การตรวจสอบสิทธิ์ หลังจากการอ้างอิงที่ระบุไว้อย่างชัดเจนล้มเหลว
• การโหลดใหม่และการตรวจสอบการรีสตาร์ตจะแยกเจ้าของที่มีสิทธิ์และมีการแมป เอกลักษณ์การอ้างอิงที่ไม่เปลี่ยนแปลง ซึ่งมีนิยามผู้ให้บริการไม่เปลี่ยนแปลงและสัญญาเจ้าของที่ครบถ้วนซึ่งไม่ใช่ข้อมูลลับไม่เปลี่ยนแปลง จะคงค่าที่ทราบว่าดีล่าสุดไว้ตามเดิมในสถานะเก่า; การอ้างอิงที่เปลี่ยนแปลงหรือกำหนดค่าใหม่แต่แก้ไขไม่ได้จะเผยแพร่แบบเย็นเฉพาะเจ้าของรายนั้น ความล้มเหลวแบบเข้มงวดระหว่างการโหลดใหม่จะคงสแนปช็อตที่ทำงานอยู่ก่อนหน้าไว้
• config.set, config.apply และ config.patch ยอมรับการอ้างอิงที่ยังแก้ไขไม่ได้แต่ถูกต้องตามไวยากรณ์สำหรับเจ้าของที่แยกได้ และส่งคืนรายงาน degradedSecretOwners ที่ปกปิดข้อมูลแล้ว การตรวจสอบสิทธิ์ขาเข้าของ Gateway, คอนฟิกหรือค่าที่แก้ไขแล้วซึ่งไม่ถูกต้องเชิงโครงสร้าง, การละเมิดนโยบาย และเจ้าของที่ไม่รู้จัก ยังคงถูกปฏิเสธก่อนแก้ไขดิสก์
• เจ้าของระดับเดียวกันที่มีสถานะปกติจะแก้ไขและเผยแพร่ตามปกติ แม้เจ้าของรายอื่นจะอยู่ในสถานะเย็นหรือเก่า
• การระบุโทเค็นช่องทางแยกสำหรับแต่ละครั้งอย่างชัดเจนให้กับการเรียกตัวช่วย/เครื่องมือขาออก จะไม่กระตุ้นการเปิดใช้งาน SecretRef; จุดเปิดใช้งานยังคงเป็นการเริ่มต้น การโหลดใหม่ และ secrets.reload ที่เรียกอย่างชัดเจน

สัญญาณสถานะเสื่อมและกู้คืนแล้ว

เมื่อการเปิดใช้งานระหว่างโหลดใหม่ล้มเหลวหลังจากอยู่ในสถานะปกติ OpenClaw จะเข้าสู่สถานะข้อมูลลับเสื่อม พร้อมส่งเหตุการณ์ระบบแบบครั้งเดียวและรหัสบันทึก:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

พฤติกรรม:

• สถานะเสื่อม: เจ้าของที่มีสถานะปกติจะรีเฟรช เจ้าของที่อยู่ในสถานะเก่าจะคงค่าที่ทราบว่าดีล่าสุดไว้ และเจ้าของที่อยู่ในสถานะเย็นจะยังไม่พร้อมใช้งาน
• กู้คืนแล้ว: ส่งหนึ่งครั้งหลังการเปิดใช้งานครั้งถัดไปสำเร็จ
• ความล้มเหลวซ้ำขณะที่อยู่ในสถานะเสื่อมแล้วจะบันทึกคำเตือน แต่ไม่ส่งเหตุการณ์ซ้ำ
• ความล้มเหลวแบบเข้มงวดระหว่างการเริ่มต้นจะไม่ส่งเหตุการณ์สถานะเสื่อม เนื่องจากรันไทม์ไม่เคยทำงาน การเริ่มต้นที่สำเร็จแต่มีเจ้าของอยู่ในสถานะเย็นจะบันทึกการเสื่อมของเจ้าของ แต่ไม่ส่งเหตุการณ์ของตัวโหลดใหม่
• ความล้มเหลวระหว่างการเริ่มต้นและโหลดใหม่ในขอบเขตการอ้างอิงจะส่งคำเตือน SECRETS_DEGRADED แบบมีโครงสร้างสำหรับเจ้าของแต่ละรายที่ได้รับผลกระทบ การหยุดให้บริการในขอบเขตผู้ให้บริการจะส่งคำเตือน SECRETS_PROVIDER_DEGRADED หนึ่งรายการ พร้อมผู้ให้บริการและรายชื่อเจ้าของที่ได้รับผลกระทบทั้งหมด แทนการแจ้งความล้มเหลวของผู้ให้บริการซ้ำสำหรับเจ้าของแต่ละราย คำเตือนประกอบด้วยเหตุผลที่ปกปิดข้อมูลแล้ว สถานะเจ้าของ cold หรือ stale และคำแนะนำให้ลองใหม่ openclaw secrets reload คำเตือนจะไม่รวมค่าที่แก้ไขแล้วหรือรหัส SecretRef
• openclaw doctor แสดงรายชื่อเจ้าของที่อยู่ในสถานะเย็นและเก่า พร้อมเส้นทางคอนฟิกที่ได้รับผลกระทบ เหตุผลที่ปกปิดข้อมูลแล้ว และคำแนะนำในการลองใหม่

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

เส้นทางคำสั่งสามารถเลือกรับการแก้ไข SecretRef ที่รองรับผ่าน RPC สแนปช็อตของ Gateway ได้ โดยมีพฤติกรรมหลักสองแบบ:

หมายเหตุอื่นๆ:

• การรีเฟรชสแนปช็อตหลังการหมุนเวียนข้อมูลลับของแบ็กเอนด์ดำเนินการโดย openclaw secrets reload
• เมธอด RPC ของ Gateway ที่เส้นทางคำสั่งเหล่านี้ใช้: secrets.resolve

เวิร์กโฟลว์การตรวจสอบและกำหนดค่า

โฟลว์เริ่มต้นสำหรับผู้ปฏิบัติงาน:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

อย่าถือว่าการย้ายข้อมูลเสร็จสมบูรณ์จนกว่าการตรวจสอบซ้ำจะไม่พบปัญหา หากการตรวจสอบยังรายงานค่าข้อความธรรมดาที่จัดเก็บอยู่ ความเสี่ยงที่เอเจนต์จะเข้าถึงยังคงอยู่ แม้ API ขณะรันไทม์จะส่งคืนค่าที่ปกปิดข้อมูลแล้วก็ตาม

หากบันทึกแผนแทนการใช้แผนระหว่าง configure ให้ใช้แผนที่บันทึกไว้นั้นด้วย openclaw secrets apply --from <plan-path> ก่อนตรวจสอบซ้ำ

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

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

แบบจำลองความปลอดภัย:

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

หมายเหตุความเข้ากันได้กับการตรวจสอบสิทธิ์รุ่นเก่า

สำหรับข้อมูลประจำตัวแบบคงที่ รันไทม์ไม่ต้องพึ่งพาพื้นที่จัดเก็บการตรวจสอบสิทธิ์รุ่นเก่าที่เป็นข้อความธรรมดาอีกต่อไป

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

หมายเหตุเกี่ยวกับ Web UI

ยูเนียน SecretInput บางรายการกำหนดค่าในโหมดตัวแก้ไขข้อมูลดิบได้ง่ายกว่าโหมดฟอร์ม

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

• การยืนยันตัวตน - การตั้งค่าการยืนยันตัวตน
• CLI: ข้อมูลลับ - คำสั่ง CLI
• SecretRefs ของ Vault - การตั้งค่าผู้ให้บริการ HashiCorp Vault
• ตัวแปรสภาพแวดล้อม - ลำดับความสำคัญของสภาพแวดล้อม
• พื้นผิวข้อมูลประจำตัว SecretRef - พื้นผิวข้อมูลประจำตัว
• สัญญาแผนการนำข้อมูลลับไปใช้ - รายละเอียดสัญญาแผน
• ความปลอดภัย - แนวทางด้านความปลอดภัย