---
read_when:
    - กำลังดำเนินการเกี่ยวกับการแก้ไขโปรไฟล์การยืนยันตัวตนหรือการกำหนดเส้นทางข้อมูลรับรอง
    - การแก้ไขข้อบกพร่องของการยืนยันตัวตนโมเดลที่ล้มเหลวหรือลำดับโปรไฟล์
summary: ความหมายเชิงหลักเกณฑ์ของการมีสิทธิ์ใช้ข้อมูลรับรองและการแก้ไขค่าข้อมูลรับรองสำหรับโปรไฟล์การยืนยันตัวตน
title: ความหมายของข้อมูลรับรองการยืนยันตัวตน
x-i18n:
    generated_at: "2026-07-12T15:50:08Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6b0516b1bb23f400d5ac5fd39a628736034440216ac22823eef061b38564dff0
    source_path: auth-credential-semantics.md
    workflow: 16
---

ความหมายเชิงพฤติกรรมเหล่านี้ทำให้ลักษณะการยืนยันตัวตนในช่วงเลือกและขณะรันทำงานสอดคล้องกัน โดยใช้ร่วมกันใน:

- `resolveAuthProfileOrder` (การจัดลำดับโปรไฟล์)
- `resolveApiKeyForProfile` (การแก้ไขข้อมูลประจำตัวขณะรัน)
- `openclaw models status --probe`
- การตรวจสอบการยืนยันตัวตนของ `openclaw doctor` (`doctor-auth`)

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

ผลการตรวจสอบประกอบด้วยกลุ่ม `status` (`ok`, `auth`, `rate_limit`, `billing`, `timeout`, `format`, `unknown`, `no_model`) พร้อม `reasonCode` ที่คงที่เมื่อการตรวจสอบยังไม่ถึงขั้นเรียกโมเดล:

| `reasonCode`             | ความหมาย                                                                                       |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| `excluded_by_auth_order` | โปรไฟล์ถูกละเว้นจากลำดับการยืนยันตัวตนที่ระบุไว้อย่างชัดเจนสำหรับผู้ให้บริการนั้น                |
| `missing_credential`     | ไม่ได้กำหนดข้อมูลประจำตัวแบบอินไลน์หรือ SecretRef                                               |
| `expired`                | ค่า `expires` ของโทเค็นเป็นเวลาที่ผ่านไปแล้ว                                                     |
| `invalid_expires`        | `expires` ไม่ใช่ค่าประทับเวลา Unix หน่วยมิลลิวินาทีแบบจำนวนบวกที่ถูกต้อง                         |
| `unresolved_ref`         | ไม่สามารถแก้ไข SecretRef ที่กำหนดค่าไว้ได้                                                       |
| `ineligible_profile`     | โปรไฟล์เข้ากันไม่ได้กับการกำหนดค่าผู้ให้บริการ (รวมถึงข้อมูลคีย์ที่มีรูปแบบไม่ถูกต้อง)             |
| `no_model`               | มีข้อมูลประจำตัว แต่ไม่สามารถระบุโมเดลที่เป็นตัวเลือกสำหรับการตรวจสอบได้                          |

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

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

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

### กฎคุณสมบัติ

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

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

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

## ความสามารถในการพกพาสำเนาของเอเจนต์

การสืบทอดการยืนยันตัวตนของเอเจนต์ใช้การอ่านผ่าน เมื่อเอเจนต์ไม่มีโปรไฟล์ภายใน จะใช้โปรไฟล์จากที่เก็บของเอเจนต์เริ่มต้น/หลักขณะรัน โดยไม่คัดลอกข้อมูลลับไปยังที่เก็บข้อมูลประจำตัวของตนเอง (`agents/<agentId>/agent/openclaw-agent.sqlite`)

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

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

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

## เส้นทางการยืนยันตัวตนที่ใช้เฉพาะการกำหนดค่า

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

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

## การกรองตามลำดับการยืนยันตัวตนที่ระบุไว้อย่างชัดเจน

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

## การระบุเป้าหมายการตรวจสอบ

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

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

- ข้อมูลประจำตัวสำหรับขณะรันเท่านั้นที่ CLI ภายนอกเป็นเจ้าของ (Claude CLI สำหรับ `claude-cli`, Codex CLI สำหรับ `openai`, MiniMax CLI สำหรับ `minimax-portal`) จะถูกค้นหาเฉพาะเมื่อผู้ให้บริการ รันไทม์ หรือโปรไฟล์การยืนยันตัวตนอยู่ในขอบเขตของการดำเนินการปัจจุบัน หรือเมื่อมีโปรไฟล์ภายในที่จัดเก็บไว้สำหรับแหล่งภายนอกนั้นอยู่แล้ว
- ผู้เรียกใช้ที่เก็บการยืนยันตัวตนจะเลือกโหมดการค้นหา CLI ภายนอกอย่างชัดเจน ได้แก่ `none` สำหรับเฉพาะการยืนยันตัวตนที่คงอยู่/ของ Plugin, `existing` สำหรับรีเฟรชโปรไฟล์ CLI ภายนอกที่จัดเก็บไว้แล้ว หรือ `scoped` สำหรับชุดผู้ให้บริการ/โปรไฟล์ที่เฉพาะเจาะจง
- เส้นทางแบบอ่านอย่างเดียว/สถานะจะส่ง `allowKeychainPrompt: false` โดยใช้เฉพาะข้อมูลประจำตัวของ CLI ภายนอกที่เก็บในไฟล์ และไม่อ่านหรือนำผลลัพธ์จาก macOS Keychain กลับมาใช้

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

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

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

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

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

`Auth profile credentials are missing or expired.`

รายละเอียดที่เข้าใจง่ายและรหัสเหตุผลที่คงที่จะตามมาในบรรทัดถัดไปในรูปแบบ `↳ Auth reason [code]: ...`

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

- [การจัดการข้อมูลลับ](/th/gateway/secrets)
- [ที่เก็บการยืนยันตัวตน](/th/concepts/oauth)