---
read_when:
    - กำลังทำงานกับการแก้ไขโปรไฟล์การตรวจสอบสิทธิ์หรือการกำหนดเส้นทางข้อมูลประจำตัว
    - การดีบักความล้มเหลวในการตรวจสอบสิทธิ์ของโมเดลหรือลำดับโปรไฟล์
summary: ความหมายเชิงมาตรฐานของการเข้าเกณฑ์และการค้นหาข้อมูลรับรองสำหรับโปรไฟล์การยืนยันตัวตน
title: ความหมายของข้อมูลประจำตัวการยืนยันตัวตน
x-i18n:
    generated_at: "2026-06-27T17:08:58Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 591c0384e1d43512252aaa7b362141b6bc93183b30b5847168758f86127f0663
    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. 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 ที่มีเฉพาะ config

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

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

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

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

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

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

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

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

## ตัวคุ้มกันนโยบาย OAuth SecretRef

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

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

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

`Auth profile credentials are missing or expired.`

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

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

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