การจัดการความลับ

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

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

ความลับจะถูกแก้ค่าเป็นสแนปช็อตรันไทม์ในหน่วยความจำ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

การตรวจล่วงหน้าของข้อมูลอ้างอิงระหว่างออนบอร์ด

เมื่อการออนบอร์ดทำงานในโหมดโต้ตอบและคุณเลือกพื้นที่จัดเก็บ SecretRef OpenClaw จะตรวจสอบล่วงหน้าก่อนบันทึก:

• Env refs: ตรวจสอบชื่อ env var และยืนยันว่าค่าที่ไม่ว่างมองเห็นได้ระหว่างการตั้งค่า
• Provider refs (file หรือ exec): ตรวจสอบการเลือกผู้ให้บริการ แก้ค่า id และตรวจชนิดของค่าที่แก้ได้
• เส้นทางการใช้ Quickstart ซ้ำ: เมื่อ gateway.auth.token เป็น SecretRef อยู่แล้ว การออนบอร์ดจะแก้ค่าก่อนเริ่ม probe/dashboard bootstrap (สำหรับ ref แบบ 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", // or "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",    },    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" } }}

API keys ที่สำรองด้วยไฟล์

อย่าใส่สตริง file:... ในบล็อก env ของคอนฟิก บล็อก 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 pointer แบบสัมบูรณ์ เช่น "/providers/xai/apiKey"

ดู พื้นผิวข้อมูลประจำตัว SecretRef สำหรับ ฟิลด์คอนฟิกที่ยอมรับ SecretRefs

ตัวอย่าง integration ของ 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: {      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, // 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" },      },    },  },}

#!/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(`Failed to parse request: ${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 exited ${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, // 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

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

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

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

วัสดุการยืนยันตัวตน SSH ของ sandbox

แบ็กเอนด์ sandbox ssh หลักยังรองรับ SecretRefs สำหรับวัสดุการยืนยันตัวตน 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" },        },      },    },  },}

พฤติกรรม runtime:

• OpenClaw แก้ ref เหล่านี้ระหว่างการเปิดใช้งาน sandbox ไม่ใช่แบบ lazy ระหว่างการเรียก SSH แต่ละครั้ง
• ค่าที่แก้แล้วจะถูกเขียนไปยังไฟล์ชั่วคราวพร้อมสิทธิ์แบบจำกัด และใช้ใน config SSH ที่สร้างขึ้น
• หากแบ็กเอนด์ sandbox ที่มีผลไม่ใช่ ssh ref เหล่านี้จะยังไม่ทำงานและไม่บล็อกการเริ่มต้น

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

ข้อมูลประจำตัวที่รองรับและไม่รองรับแบบ canonical แสดงอยู่ใน:

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

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

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

สัญญาณเตือนและ audit:

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

พฤติกรรมความเข้ากันได้ของ Google Chat:

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

ทริกเกอร์การเปิดใช้งาน

การเปิดใช้งาน secret ทำงานเมื่อ:

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

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

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

สัญญาณ degraded และ recovered

เมื่อการเปิดใช้งานระหว่าง reload ล้มเหลวหลังจากสถานะปกติ OpenClaw จะเข้าสู่สถานะ secrets แบบ degraded

อีเวนต์ระบบแบบครั้งเดียวและรหัส log:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

พฤติกรรม:

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

การแก้พาธคำสั่ง

พาธคำสั่งสามารถเลือกใช้การแก้ SecretRef ที่รองรับผ่าน gateway snapshot RPC ได้

มีพฤติกรรมกว้าง ๆ สองแบบ:

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

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

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

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

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

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

หากคุณบันทึกแผนแทนการนำไปใช้ระหว่าง 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

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

โมเดลความปลอดภัย:

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

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

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

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

หมายเหตุ Web UI

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

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

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