การยืนยันตัวตน

OpenClaw รองรับ OAuth และคีย์ API สำหรับผู้ให้บริการโมเดล สำหรับโฮสต์ Gateway ที่ทำงานตลอดเวลา คีย์ API เป็นตัวเลือกที่คาดการณ์พฤติกรรมได้มากที่สุด ส่วนขั้นตอนการสมัครสมาชิก/OAuth ก็ใช้งานได้เช่นกันเมื่อตรงกับรูปแบบบัญชีของผู้ให้บริการของคุณ

• ขั้นตอน OAuth ฉบับเต็มและโครงสร้างการจัดเก็บ: /concepts/oauth
• การยืนยันตัวตนที่ใช้ SecretRef (env/file/exec เป็นแหล่งข้อมูล): การจัดการข้อมูลลับ
• คุณสมบัติที่เข้าเกณฑ์ของข้อมูลประจำตัว/รหัสเหตุผลที่ models status --probe ใช้: ความหมายของข้อมูลประจำตัวสำหรับการยืนยันตัวตน

การตั้งค่าที่แนะนำ: คีย์ API (ผู้ให้บริการใดก็ได้)

1. สร้างคีย์ API ในคอนโซลของผู้ให้บริการ
2. ใส่คีย์ไว้บน โฮสต์ Gateway (เครื่องที่เรียกใช้ openclaw gateway):

export <PROVIDER>_API_KEY="..."openclaw models status

3. หาก Gateway ทำงานภายใต้ systemd/launchd ให้ใส่คีย์ใน ~/.openclaw/.env เพื่อให้ดีมอนอ่านได้:

cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF

4. เริ่มกระบวนการ Gateway (หรือดีมอน) ใหม่ แล้วตรวจสอบอีกครั้ง:

openclaw models statusopenclaw doctor

openclaw onboard ยังสามารถจัดเก็บคีย์ API เพื่อให้ดีมอนใช้งานได้ หากคุณไม่ต้องการจัดการตัวแปรสภาพแวดล้อมด้วยตนเอง โปรดดู ตัวแปรสภาพแวดล้อม สำหรับลำดับความสำคัญทั้งหมดในการโหลดตัวแปรสภาพแวดล้อม (env.shellEnv, ~/.openclaw/.env, systemd/launchd)

Anthropic: การใช้ Claude CLI ซ้ำ

การยืนยันตัวตนด้วย setup-token ของ Anthropic ยังคงเป็นวิธีที่รองรับ การใช้ Claude CLI ซ้ำ (การใช้งานแบบ claude -p) ก็ได้รับอนุญาตสำหรับการผสานรวมนี้เช่นกัน เมื่อมีการเข้าสู่ระบบ Claude CLI บนโฮสต์ วิธีนี้เป็นวิธีที่แนะนำสำหรับการใช้งานภายในเครื่อง/เดสก์ท็อป สำหรับโฮสต์ Gateway ที่ทำงานระยะยาว คีย์ API ของ Anthropic ยังคงเป็นตัวเลือกที่คาดการณ์พฤติกรรมได้มากที่สุด พร้อมการควบคุมการเรียกเก็บเงินฝั่งเซิร์ฟเวอร์อย่างชัดเจน

การตั้งค่าโฮสต์สำหรับการใช้ Claude CLI ซ้ำ:

# เรียกใช้บนโฮสต์ Gatewayclaude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

กระบวนการนี้มีสองขั้นตอน: เข้าสู่ระบบ Claude Code กับ Anthropic บนโฮสต์ จากนั้นบอก OpenClaw ให้กำหนดเส้นทางการเลือกโมเดล Anthropic ผ่านแบ็กเอนด์ claude-cli ภายในเครื่อง และจัดเก็บโปรไฟล์การยืนยันตัวตน OpenClaw ที่สอดคล้องกัน

หาก claude ไม่อยู่ใน PATH ให้ติดตั้ง Claude Code หรือตั้งค่า agents.defaults.cliBackends.claude-cli.command เป็นพาธของไฟล์ไบนารี

การป้อนโทเค็นด้วยตนเอง

ใช้ได้กับผู้ให้บริการทุกราย โดยจะเขียนข้อมูลไปยังที่จัดเก็บการยืนยันตัวตน SQLite ประจำเอเจนต์และอัปเดตการกำหนดค่า:

openclaw models auth paste-token --provider openrouter

OpenClaw อ่านโปรไฟล์การยืนยันตัวตนจาก openclaw-agent.sqlite ของแต่ละเอเจนต์ รายละเอียดปลายทาง (baseUrl, api, รหัสโมเดล, ส่วนหัว, ระยะหมดเวลา) ต้องอยู่ภายใต้ models.providers.<id> ใน openclaw.json หรือ models.json ไม่ใช่ในโปรไฟล์การยืนยันตัวตน

หากการติดตั้งรุ่นเก่ายังคงมี auth-profiles.json, auth-state.json หรือโครงสร้างแบบแบน เช่น { "openrouter": { "apiKey": "..." } } ให้เรียกใช้ openclaw doctor --fix เพื่อนำเข้าข้อมูลไปยัง SQLite โดย doctor จะเก็บข้อมูลสำรองที่มีการประทับเวลาไว้ข้างไฟล์ JSON ต้นฉบับ

เส้นทางการยืนยันตัวตนภายนอก เช่น auth: "aws-sdk" ของ Bedrock ไม่ใช่ข้อมูลประจำตัว สำหรับเส้นทาง Bedrock ที่มีชื่อ ให้ตั้งค่า auth.profiles.<id>.mode: "aws-sdk" ใน openclaw.json — อย่าเขียน type: "aws-sdk" ลงในที่จัดเก็บโปรไฟล์การยืนยันตัวตน openclaw doctor --fix จะย้ายตัวบ่งชี้ AWS SDK แบบเดิมจากที่จัดเก็บข้อมูลประจำตัวไปยังข้อมูลเมตาของการกำหนดค่า

ข้อมูลประจำตัวที่ใช้ SecretRef

• ข้อมูลประจำตัว api_key สามารถใช้ keyRef: { source, provider, id }
• ข้อมูลประจำตัว token สามารถใช้ tokenRef: { source, provider, id }
• โปรไฟล์โหมด OAuth ไม่ยอมรับข้อมูลประจำตัว SecretRef: หาก auth.profiles.<id>.mode เป็น "oauth" ระบบจะปฏิเสธ keyRef/tokenRef ที่ใช้ SecretRef สำหรับโปรไฟล์นั้น

การตรวจสอบสถานะการยืนยันตัวตนของโมเดล

openclaw models statusopenclaw doctor

การตรวจสอบที่เหมาะสำหรับระบบอัตโนมัติ โดยออกด้วยรหัส 1 เมื่อหมดอายุ/ไม่มีข้อมูล และรหัส 2 เมื่อใกล้หมดอายุ:

openclaw models status --check

การตรวจสอบการยืนยันตัวตนแบบสด (เพิ่ม --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency หรือ --probe-max-tokens เพื่อจำกัดขอบเขต):

openclaw models status --probe

หมายเหตุ:

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

สคริปต์การปฏิบัติงานเพิ่มเติม (systemd/Termux): สคริปต์ตรวจติดตามการยืนยันตัวตน

การหมุนเวียนคีย์ API (Gateway)

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

ลำดับความสำคัญของคีย์สำหรับผู้ให้บริการแต่ละราย:

1. OPENCLAW_LIVE_<PROVIDER>_KEY (ค่าแทนที่ค่าเดียว โดยตรึงไว้ที่คีย์เดียว)
2. <PROVIDER>_API_KEYS (รายการที่คั่นด้วยจุลภาค/ช่องว่าง/อัฒภาค)
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_* (ตัวแปรสภาพแวดล้อมใด ๆ ที่มีคำนำหน้านี้)

ผู้ให้บริการ Google (google, google-vertex) จะใช้ GOOGLE_API_KEY เป็นทางเลือกสำรองเพิ่มเติม รายการที่รวมกันจะถูกลบรายการซ้ำก่อนใช้งาน

OpenClaw จะหมุนเวียนไปยังคีย์ถัดไปเฉพาะเมื่อข้อความแสดงข้อผิดพลาดตรงกับ: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted หรือ too many requests ข้อผิดพลาดอื่นจะไม่ถูกลองใหม่ด้วยคีย์สำรอง หากคีย์ทั้งหมดล้มเหลว ระบบจะส่งคืนข้อผิดพลาดสุดท้ายจากความพยายามครั้งสุดท้าย

การลบข้อมูลการยืนยันตัวตนที่บันทึกไว้ไม่ได้เพิกถอนคีย์ที่ผู้ให้บริการ — เมื่อคุณต้องการทำให้คีย์ใช้ไม่ได้ในฝั่งผู้ให้บริการ ให้หมุนเวียนหรือเพิกถอนคีย์ในแดชบอร์ดของผู้ให้บริการ

การลบการยืนยันตัวตนของผู้ให้บริการขณะ Gateway ทำงาน

เมื่อคุณลบการยืนยันตัวตนของผู้ให้บริการผ่านระนาบควบคุมของ Gateway OpenClaw จะลบโปรไฟล์การยืนยันตัวตนที่บันทึกไว้สำหรับผู้ให้บริการนั้น และยุติการแชต/การทำงานของเอเจนต์ที่กำลังใช้งานอยู่ซึ่งผู้ให้บริการของโมเดลที่เลือกตรงกับผู้ให้บริการที่ถูกลบ การทำงานที่ถูกยุติจะปล่อยเหตุการณ์การยกเลิก/วงจรชีวิตตามปกติพร้อม stopReason: "auth-revoked" เพื่อให้ไคลเอนต์ที่เชื่อมต่ออยู่แสดงได้ว่าการทำงานหยุดลงเนื่องจากข้อมูลประจำตัวถูกลบ

การควบคุมว่าจะใช้ข้อมูลประจำตัวใด

OpenAI และรหัส openai-codex แบบเดิม

ทั้งโปรไฟล์คีย์ API ของ OpenAI และโปรไฟล์ OAuth ของ ChatGPT/Codex ใช้รหัสผู้ให้บริการมาตรฐาน openai ใช้รหัสโปรไฟล์ openai:* และ auth.order.openai สำหรับการกำหนดค่าใหม่

หากคุณพบ openai-codex ในการกำหนดค่าเก่า รหัสโปรไฟล์การยืนยันตัวตน หรือ auth.order.openai-codex ให้ถือว่าเป็นข้อมูลนำเข้าสำหรับการย้ายข้อมูลแบบเดิม — อย่าสร้างโปรไฟล์ openai-codex ใหม่ ให้เรียกใช้:

openclaw doctor --fixopenclaw models auth list --provider openai

Doctor จะเขียนรหัสโปรไฟล์ openai-codex:* แบบเดิมและรายการ auth.order.openai-codex ใหม่ให้เป็นเส้นทางมาตรฐาน openai สำหรับการกำหนดเส้นทางโมเดล/รันไทม์เฉพาะ OpenAI โปรดดู OpenAI

ระหว่างการเข้าสู่ระบบ (CLI)

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-id ช่วยแยกการเข้าสู่ระบบ OAuth หลายรายการสำหรับผู้ให้บริการเดียวกันภายในเอเจนต์หนึ่งตัว

--force จะลบโปรไฟล์การยืนยันตัวตนที่บันทึกไว้สำหรับผู้ให้บริการนั้นในไดเรกทอรีของเอเจนต์ที่เลือก จากนั้นเรียกใช้ขั้นตอนการยืนยันตัวตนเดิมอีกครั้ง ใช้ตัวเลือกนี้เมื่อโปรไฟล์ที่บันทึกไว้ค้าง หมดอายุ หรือเชื่อมโยงกับบัญชีที่ไม่ถูกต้อง ตัวเลือกนี้ไม่เพิกถอนข้อมูลประจำตัวที่ผู้ให้บริการ

openclaw models auth login --provider anthropic --force

ต่อเซสชัน (คำสั่งแชต)

• /model <alias-or-id>@<profileId> ตรึงข้อมูลประจำตัวของผู้ให้บริการรายการหนึ่งสำหรับเซสชันปัจจุบัน (ตัวอย่างรหัสโปรไฟล์: anthropic:default, anthropic:work)
• /model (หรือ /model list) แสดงตัวเลือกแบบกะทัดรัด ส่วน /model status แสดงมุมมองแบบเต็ม (ตัวเลือกโมเดล + โปรไฟล์การยืนยันตัวตนถัดไป รวมถึงรายละเอียดปลายทางของผู้ให้บริการเมื่อมีการกำหนดค่าไว้)

หากคุณเปลี่ยนลำดับการยืนยันตัวตนหรือการตรึงโปรไฟล์สำหรับแชตที่กำลังทำงานอยู่ ให้ส่ง /new หรือ /reset เพื่อเริ่มเซสชันใหม่ — เซสชันเดิมจะยังคงใช้โมเดล/โปรไฟล์ที่เลือกไว้ในปัจจุบันจนกว่าจะรีเซ็ต

ต่อเอเจนต์ (การแทนที่ผ่าน CLI)

การแทนที่ลำดับการยืนยันตัวตนจะถูกจัดเก็บในสถานะการยืนยันตัวตน SQLite ของเอเจนต์นั้น:

openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

ใช้ --agent <id> เพื่อระบุเอเจนต์ที่ต้องการ หากละไว้จะใช้เอเจนต์เริ่มต้นที่กำหนดค่าไว้ openclaw models status --probe จะแสดงโปรไฟล์ที่จัดเก็บไว้แต่ถูกละเว้นเป็น excluded_by_auth_order แทนการข้ามไปโดยไม่แจ้ง

การแก้ไขปัญหา

"ไม่พบข้อมูลประจำตัว"

กำหนดค่าคีย์ API ของ Anthropic บน โฮสต์ Gateway หรือตั้งค่าเส้นทาง setup-token ของ Anthropic แล้วตรวจสอบอีกครั้ง:

openclaw models status

โทเค็นใกล้หมดอายุ/หมดอายุแล้ว

เรียกใช้ openclaw models status เพื่อดูว่าโปรไฟล์ใดกำลังจะหมดอายุ หากโปรไฟล์โทเค็น Anthropic ไม่มีอยู่หรือหมดอายุ ให้รีเฟรชผ่าน setup-token หรือย้ายไปใช้คีย์ API ของ Anthropic

เนื้อหาที่เกี่ยวข้อง

• การจัดการข้อมูลลับ
• การเข้าถึงระยะไกล
• การจัดเก็บข้อมูลการยืนยันตัวตน