---
read_when:
    - การทำงานกับการระบุโปรไฟล์การตรวจสอบสิทธิ์หรือการกำหนดเส้นทางข้อมูลรับรอง
    - การดีบักความล้มเหลวในการยืนยันตัวตนของโมเดลหรือลำดับโปรไฟล์
summary: ความหมายเชิงมาตรฐานของคุณสมบัติการใช้ข้อมูลรับรองและการแก้ไขสำหรับ auth profiles
title: ความหมายของข้อมูลรับรองการยืนยันตัวตน
x-i18n:
    generated_at: "2026-05-07T13:13:14Z"
    model: gpt-5.5
    provider: openai
    source_hash: 2d916ff95ca2ac1fe21e66f64b887b1df1e6b97d7dcc681e5bb9a9dee8ce9473
    source_path: auth-credential-semantics.md
    workflow: 16
---

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

- `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.`

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

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

- [การจัดการความลับ](/th/gateway/secrets)
- [การจัดเก็บการยืนยันตัวตน](/th/concepts/oauth)