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

เอกสารนี้กำหนดความหมายเชิงมาตรฐานของคุณสมบัติที่ใช้ได้และการแก้ไขข้อมูลรับรอง ซึ่งใช้ทั่วทั้ง:

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

เป้าหมายคือเพื่อให้พฤติกรรมในช่วงเลือกและช่วงรันไทม์สอดคล้องกัน

## รหัสเหตุผลของ probe ที่เสถียร

- `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. ref ที่แก้ไขค่าไม่ได้จะแสดง `unresolved_ref` ในเอาต์พุต `models status --probe`

## การพกพาสำเนาของเอเจนต์

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

โฟลว์การคัดลอกที่ชัดเจน เช่น `openclaw agents add` ใช้นโยบายการพกพานี้:

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

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

## การกรองลำดับ auth ที่ชัดเจน

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

## การแก้ไขค่าเป้าหมาย probe

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

## การค้นพบข้อมูลรับรองของ CLI ภายนอก

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

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

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

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

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

`Auth profile credentials are missing or expired.`

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

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

- [การจัดการความลับ](/th/gateway/secrets)
- [พื้นที่จัดเก็บ auth](/th/concepts/oauth)
