สัญญาแผน apply ของ secrets

หน้านี้กำหนดสัญญาแบบเข้มงวดที่ถูกบังคับใช้โดย openclaw secrets apply

หากเป้าหมายไม่ตรงตามกฎเหล่านี้ apply จะล้มเหลวก่อนมีการแก้ไข configuration

# รูปแบบไฟล์แผน

openclaw secrets apply --from <plan.json> คาดหวัง targets array ของเป้าหมายในแผน:

{
  version: 1,
  protocolVersion: 1,
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.openai.apiKey",
      pathSegments: ["models", "providers", "openai", "apiKey"],
      providerId: "openai",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
    {
      type: "auth-profiles.api_key.key",
      path: "profiles.openai:default.key",
      pathSegments: ["profiles", "openai:default", "key"],
      agentId: "main",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
  ],
}

# ขอบเขตเป้าหมายที่รองรับ

ระบบยอมรับเป้าหมายในแผนสำหรับ paths ของข้อมูลรับรองที่รองรับใน:

• SecretRef Credential Surface

# พฤติกรรมของชนิดเป้าหมาย

กฎทั่วไป:

• target.type ต้องเป็นค่าที่รู้จักและต้องตรงกับรูปแบบ target.path ที่ถูก normalize แล้ว

compatibility aliases ยังยอมรับได้สำหรับแผนเดิมที่มีอยู่:

• models.providers.apiKey
• skills.entries.apiKey
• channels.googlechat.serviceAccount

# กฎการตรวจสอบพาธ

แต่ละเป้าหมายจะถูกตรวจสอบด้วยเงื่อนไขทั้งหมดต่อไปนี้:

• type ต้องเป็นชนิดเป้าหมายที่รู้จัก
• path ต้องเป็น dot path ที่ไม่ว่าง
• pathSegments สามารถละได้ หากระบุมา จะต้อง normalize แล้วได้ path ที่ตรงกับ path ทุกประการ
• segments ที่ต้องห้ามจะถูกปฏิเสธ: __proto__, prototype, constructor
• path ที่ normalize แล้วต้องตรงกับรูปแบบ path ที่ลงทะเบียนไว้สำหรับชนิดเป้าหมายนั้น
• หากมีการตั้ง providerId หรือ accountId ไว้ ค่านั้นต้องตรงกับ id ที่ถูกเข้ารหัสอยู่ใน path
• เป้าหมายของ auth-profiles.json ต้องมี agentId
• เมื่อสร้าง mapping ใหม่ใน auth-profiles.json ให้รวม authProfileProvider มาด้วย

# พฤติกรรมเมื่อเกิดความล้มเหลว

หากเป้าหมายใดไม่ผ่านการตรวจสอบ apply จะออกพร้อมข้อผิดพลาดเช่น:

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

จะไม่มีการเขียนใดถูกคอมมิตสำหรับแผนที่ไม่ถูกต้อง

# พฤติกรรมการยินยอมของ exec provider

• --dry-run จะข้ามการตรวจสอบ exec SecretRef เป็นค่าเริ่มต้น
• แผนที่มี exec SecretRefs/providers จะถูกปฏิเสธในโหมดเขียน เว้นแต่จะตั้ง --allow-exec
• เมื่อตรวจสอบ/นำแผนที่มี exec ไปใช้ ให้ส่ง --allow-exec ทั้งในคำสั่ง dry-run และคำสั่งเขียนจริง

# หมายเหตุเรื่องขอบเขต runtime และ audit

• รายการ auth-profiles.json แบบ ref-only (keyRef/tokenRef) ถูกรวมอยู่ในการ resolve ขณะรันและในขอบเขตการ audit
• secrets apply จะเขียนเป้าหมาย openclaw.json ที่รองรับ เป้าหมาย auth-profiles.json ที่รองรับ และ scrub targets แบบไม่บังคับ

# การตรวจสอบสำหรับ operator

# ตรวจสอบแผนโดยไม่เขียน
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# จากนั้นจึง apply จริง
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# สำหรับแผนที่มี exec ให้ opt in อย่างชัดเจนทั้งสองโหมด
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

หาก apply ล้มเหลวพร้อมข้อความ invalid target path ให้สร้างแผนใหม่ด้วย openclaw secrets configure หรือแก้ไข target path ให้เป็นรูปแบบที่รองรับตามด้านบน

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

• Secrets Management
• CLI secrets
• SecretRef Credential Surface
• Configuration Reference