ความหมายของข้อมูลรับรองการยืนยันตัวตน

เอกสารนี้กำหนดความหมายเชิงมาตรฐานของการมีสิทธิ์ใช้ข้อมูลประจำตัวและการแก้ค่าที่ใช้ร่วมกันใน:

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

เป้าหมายคือทำให้พฤติกรรมขณะเลือกและขณะรันสอดคล้องกัน

# รหัสเหตุผลการตรวจสอบที่เสถียร

• ok
• excluded_by_auth_order
• missing_credential
• invalid_expires
• expired
• unresolved_ref
• no_model

# ข้อมูลประจำตัวแบบโทเค็น

ข้อมูลประจำตัวแบบโทเค็น (type: "token") รองรับ token แบบระบุโดยตรงและ/หรือ tokenRef

# กฎการมีสิทธิ์

1. โปรไฟล์โทเค็นไม่มีสิทธิ์เมื่อไม่มีทั้ง token และ tokenRef
2. expires เป็นค่าไม่บังคับ
3. หากมี expires ค่านั้นต้องเป็นตัวเลขจำกัดที่มากกว่า 0
4. หาก expires ไม่ถูกต้อง (NaN, 0, ค่าติดลบ, ค่าไม่จำกัด, หรือชนิดผิด) โปรไฟล์จะไม่มีสิทธิ์ด้วย invalid_expires
5. หาก expires อยู่ในอดีต โปรไฟล์จะไม่มีสิทธิ์ด้วย expired
6. tokenRef ไม่ข้ามการตรวจสอบความถูกต้องของ expires

# กฎการแก้ค่า

1. ความหมายของตัวแก้ค่าตรงกับความหมายการมีสิทธิ์สำหรับ expires
2. สำหรับโปรไฟล์ที่มีสิทธิ์ วัสดุโทเค็นอาจแก้ค่าได้จากค่าที่ระบุโดยตรงหรือ tokenRef
3. การอ้างอิงที่แก้ค่าไม่ได้จะสร้าง unresolved_ref ในเอาต์พุต models status --probe

# ความสามารถในการย้ายสำเนา Agent

การสืบทอดการยืนยันตัวตนของ Agent เป็นแบบอ่านทะลุ เมื่อ Agent ไม่มีโปรไฟล์ในเครื่อง Agent นั้นสามารถแก้ค่าโปรไฟล์จากที่เก็บ Agent ค่าเริ่มต้น/หลักได้ขณะรันโดยไม่ต้องคัดลอกวัสดุลับไปยัง auth-profiles.json ของตนเอง

โฟลว์การคัดลอกแบบชัดเจน เช่น openclaw agents add ใช้นโยบายความสามารถในการย้ายนี้:

• โปรไฟล์ api_key ย้ายได้ เว้นแต่ copyToAgents: false
• โปรไฟล์ token ย้ายได้ เว้นแต่ copyToAgents: false
• โปรไฟล์ oauth ไม่ย้ายได้โดยค่าเริ่มต้น เพราะ refresh token อาจใช้ได้ครั้งเดียวหรือไวต่อการหมุนเวียน
• โฟลว์ OAuth ที่ผู้ให้บริการเป็นเจ้าของอาจเลือกเข้าร่วมด้วย copyToAgents: true ได้เฉพาะเมื่อทราบว่าการคัดลอกวัสดุ refresh ข้าม Agent ปลอดภัย

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

# เส้นทางการยืนยันตัวตนแบบ config เท่านั้น

รายการ auth.profiles ที่มี mode: "aws-sdk" เป็นเมทาดาทาการกำหนดเส้นทาง ไม่ใช่ข้อมูลประจำตัวที่จัดเก็บ รายการเหล่านี้ถูกต้องเมื่อผู้ให้บริการเป้าหมายใช้ models.providers.<id>.auth: "aws-sdk" หรือเส้นทาง AWS SDK ค่าเริ่มต้นของ Amazon Bedrock ในตัว รหัสโปรไฟล์เหล่านี้อาจปรากฏใน auth.order และการแทนที่ของเซสชันได้ แม้ไม่มีรายการที่ตรงกันใน auth-profiles.json

อย่าเขียน type: "aws-sdk" ลงใน auth-profiles.json หากการติดตั้งเดิมมีเครื่องหมายดังกล่าว openclaw doctor --fix จะย้ายไปยัง auth.profiles และลบเครื่องหมายออกจากที่เก็บข้อมูลประจำตัว

# การกรองลำดับการยืนยันตัวตนแบบชัดเจน

• เมื่อมีการตั้งค่า auth.order.<provider> หรือการแทนที่ลำดับของที่เก็บการยืนยันตัวตนสำหรับผู้ให้บริการ models status --probe จะตรวจสอบเฉพาะรหัสโปรไฟล์ที่ยังอยู่ในลำดับการยืนยันตัวตนที่แก้ค่าแล้วสำหรับผู้ให้บริการนั้น
• โปรไฟล์ที่จัดเก็บไว้สำหรับผู้ให้บริการนั้นซึ่งถูกละเว้นจากลำดับแบบชัดเจนจะไม่ถูกลองเงียบ ๆ ในภายหลัง เอาต์พุตการตรวจสอบจะรายงานโปรไฟล์นั้นด้วย reasonCode: excluded_by_auth_order และรายละเอียด Excluded by auth.order for this provider.

# การแก้ค่าเป้าหมายการตรวจสอบ

• เป้าหมายการตรวจสอบอาจมาจากโปรไฟล์การยืนยันตัวตน ข้อมูลประจำตัวสภาพแวดล้อม หรือ models.json
• หากผู้ให้บริการมีข้อมูลประจำตัว แต่ OpenClaw ไม่สามารถแก้ค่าตัวเลือกโมเดลที่ตรวจสอบได้สำหรับผู้ให้บริการนั้น models status --probe จะรายงาน status: no_model พร้อม reasonCode: no_model

# การค้นหาข้อมูลประจำตัว CLI ภายนอก

• ข้อมูลประจำตัวที่เป็นของ CLI ภายนอกและใช้เฉพาะขณะรันจะถูกค้นพบเฉพาะเมื่อผู้ให้บริการ รันไทม์ หรือโปรไฟล์การยืนยันตัวตนอยู่ในขอบเขตของการดำเนินการปัจจุบัน หรือเมื่อมีโปรไฟล์ในเครื่องที่จัดเก็บไว้สำหรับแหล่งภายนอกนั้นอยู่แล้ว
• ผู้เรียกที่เก็บการยืนยันตัวตนควรเลือกโหมดค้นหา CLI ภายนอกแบบชัดเจน: none สำหรับการยืนยันตัวตนที่คงอยู่/Plugin เท่านั้น, existing สำหรับรีเฟรชโปรไฟล์ CLI ภายนอกที่จัดเก็บไว้แล้ว, หรือ scoped สำหรับชุดผู้ให้บริการ/โปรไฟล์ที่เป็นรูปธรรม
• เส้นทางอ่านอย่างเดียว/สถานะจะส่ง allowKeychainPrompt: false; เส้นทางเหล่านี้ใช้เฉพาะข้อมูลประจำตัว CLI ภายนอกที่มีไฟล์รองรับ และไม่อ่านหรือนำผลลัพธ์ macOS Keychain กลับมาใช้ซ้ำ

# ตัวป้องกันนโยบาย OAuth SecretRef

• อินพุต SecretRef ใช้สำหรับข้อมูลประจำตัวแบบคงที่เท่านั้น
• หากข้อมูลประจำตัวของโปรไฟล์เป็น type: "oauth" จะไม่รองรับอ็อบเจกต์ SecretRef สำหรับวัสดุข้อมูลประจำตัวของโปรไฟล์นั้น
• หาก auth.profiles.<id>.mode เป็น "oauth" อินพุต keyRef/tokenRef ที่รองรับด้วย SecretRef สำหรับโปรไฟล์นั้นจะถูกปฏิเสธ
• การละเมิดเป็นความล้มเหลวแบบเด็ดขาดในเส้นทางการแก้ค่าการยืนยันตัวตนตอนเริ่มต้น/โหลดซ้ำ

# ข้อความที่เข้ากันได้กับระบบเดิม

เพื่อความเข้ากันได้ของสคริปต์ ข้อผิดพลาดการตรวจสอบจะคงบรรทัดแรกนี้ไว้โดยไม่เปลี่ยนแปลง:

Auth profile credentials are missing or expired.

อาจเพิ่มรายละเอียดที่เป็นมิตรต่อมนุษย์และรหัสเหตุผลที่เสถียรในบรรทัดถัดไป

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

• การจัดการความลับ
• การจัดเก็บการยืนยันตัวตน