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

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

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

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

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

สิ่งนี้ช่วยกันการขัดข้องของผู้ให้บริการ secret ออกจากเส้นทางคำขอที่ใช้งานหนัก

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

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

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

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

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

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

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

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

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

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

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

# สัญญา 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:

{
  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

env vars ของเซิร์ฟเวอร์ MCP ที่กำหนดค่าผ่าน plugins.entries.acpx.config.mcpServers รองรับ SecretInput สิ่งนี้ช่วยกัน API keys และ 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",
                },
              },
            },
          },
        },
      },
    },
  },
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• เริ่มต้นระบบ (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

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

รหัส system event และ log แบบ one-shot:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

พฤติกรรม:

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

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

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

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

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

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

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

flow เริ่มต้นสำหรับ operator:

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

สำหรับข้อมูลประจำตัวแบบ static runtime จะไม่ขึ้นกับที่จัดเก็บ auth legacy แบบ plaintext อีกต่อไป

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

# หมายเหตุ Web UI

SecretInput unions บางรายการคอนฟิกในโหมด raw editor ได้ง่ายกว่าในโหมด form

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

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