---
read_when:
- การกำหนดค่า SecretRefs สำหรับข้อมูลรับรองของผู้ให้บริการและการอ้างอิง `auth-profiles.json`
- ดำเนินการโหลดซีเคร็ตใหม่ ตรวจสอบ กำหนดค่า และนำไปใช้อย่างปลอดภัยในสภาพแวดล้อมการผลิต
- ทำความเข้าใจการหยุดทำงานทันทีเมื่อเริ่มต้นล้มเหลว การกรองพื้นผิวที่ไม่ได้ใช้งาน และพฤติกรรมการใช้สถานะล่าสุดที่ทราบว่าทำงานได้ดี
sidebarTitle: Secrets management
summary: 'การจัดการข้อมูลลับ: สัญญา SecretRef, ลักษณะการทำงานของสแนปช็อตขณะรันไทม์ และการล้างข้อมูลแบบทางเดียวอย่างปลอดภัย'
title: การจัดการข้อมูลลับ
x-i18n:
generated_at: "2026-07-20T05:57:50Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 32
provider: openai
source_hash: bbc7d006384ab6518daadc9f9283e15954a76f95307a09b73b053017a53b112c
source_path: gateway/secrets.md
workflow: 16
---
OpenClaw รองรับ SecretRefs แบบเพิ่มต่อได้ เพื่อไม่ให้ข้อมูลรับรองที่รองรับต้องจัดเก็บเป็นข้อความธรรมดาในการกำหนดค่า
ข้อความธรรมดายังคงใช้งานได้ SecretRefs เป็นตัวเลือกที่ต้องเปิดใช้แยกตามข้อมูลรับรองแต่ละรายการ
ข้อมูลรับรองแบบข้อความธรรมดายังคงให้เอเจนต์อ่านได้ หากอยู่ในไฟล์ที่เอเจนต์ตรวจสอบได้ รวมถึง `openclaw.json`, `auth-profiles.json`, `.env` หรือไฟล์ `agents/*/agent/models.json` ที่สร้างขึ้น SecretRefs จะลดขอบเขตผลกระทบภายในเครื่องได้ก็ต่อเมื่อย้ายข้อมูลรับรองที่รองรับทั้งหมดแล้ว และ `openclaw secrets audit --check` รายงานว่าไม่มีข้อความธรรมดาตกค้าง
## โมเดลรันไทม์
- ซีเคร็ตจะถูกแก้ค่าเป็นสแนปช็อตรันไทม์ในหน่วยความจำล่วงหน้าระหว่างการเปิดใช้งาน ไม่ใช่แบบหน่วงเวลาในเส้นทางคำขอ
- การเริ่มต้น Gateway แบบ cold จะแยกความล้มเหลวของ SecretRef ที่ลองใหม่ได้ไปยังเจ้าของที่ทราบแน่ชัดซึ่งไม่ใช่ Gateway เมื่อเจ้าของนั้นรองรับการแยก เจ้าของที่แมปไว้ประกอบด้วยผู้ให้บริการโมเดลและ Skills, ผู้ให้บริการสื่อ/TTS/cron, โปรไฟล์การยืนยันตัวตนที่มีสิทธิ์, หน่วยความจำรายเอเจนต์, sandbox SSH, บัญชีช่องทาง และเส้นทาง Plugin ที่ประกาศใน manifest Gateway จะเริ่มทำงาน บันทึกเจ้าของว่าได้รับการกำหนดค่าแต่ใช้งานไม่ได้ และแสดงคำเตือนการลดระดับการทำงานที่ปกปิดข้อมูลแล้ว การยืนยันตัวตนขาเข้าของ Gateway, การอ้างอิงหรือค่าที่แก้แล้วซึ่งมีโครงสร้างไม่ถูกต้อง, เจ้าของที่ต้องล้มเหลวแบบปิด และการอ้างอิงที่ไม่ได้แมปเจ้าของรันไทม์ ยังคงทำให้การเริ่มต้นล้มเหลว
- การโหลดใหม่จะตรวจสอบเจ้าของแต่ละรายที่แมปไว้อย่างเป็นอิสระ จากนั้นเผยแพร่สแนปช็อตเดียวแบบอะตอมมิก เจ้าของที่ปกติจะได้รับการรีเฟรช เจ้าของที่มีสิทธิ์แต่ล้มเหลวจะเก็บค่าล่าสุดที่ทราบว่าใช้งานได้ และจะกลายเป็น stale เฉพาะเมื่ออัตลักษณ์ของการอ้างอิง นิยามผู้ให้บริการ และสัญญาเจ้าของส่วนที่ไม่ใช่ซีเคร็ตทั้งหมดไม่เปลี่ยนแปลง ส่วนเจ้าของที่เปลี่ยนแปลงหรือเพิ่มใหม่และล้มเหลวจะกลายเป็น cold ความล้มเหลวแบบเข้มงวดจะปฏิเสธการโหลดใหม่และคงสแนปช็อตที่ใช้งานอยู่ไว้
- การละเมิดนโยบาย (เช่น โปรไฟล์การยืนยันตัวตนโหมด OAuth ที่ใช้ร่วมกับอินพุต SecretRef) จะทำให้การเปิดใช้งานล้มเหลวก่อนสลับรันไทม์
- คำขอรันไทม์จะอ่านเฉพาะสแนปช็อตในหน่วยความจำที่ใช้งานอยู่ ข้อมูลรับรอง SecretRef ของผู้ให้บริการโมเดลจะผ่านพื้นที่จัดเก็บการยืนยันตัวตนและตัวเลือกสตรีมในรูป sentinel ภายในโปรเซสจนถึงขาออก เส้นทางการนำส่งขาออก (การนำส่งการตอบกลับ/เธรดของ Discord, การส่งการดำเนินการของ Telegram) จะอ่านสแนปช็อตนั้นเช่นกัน และจะไม่แก้ค่าการอ้างอิงใหม่ในการส่งแต่ละครั้ง
แนวทางนี้ทำให้เหตุขัดข้องของผู้ให้บริการซีเคร็ตไม่กระทบเส้นทางคำขอที่ใช้งานหนัก
การป้องกันขาเข้าของ Gateway, การกำหนดค่าหรือค่าที่แก้แล้วซึ่งมีโครงสร้างไม่ถูกต้อง, การละเมิดนโยบาย และเจ้าของที่ไม่ทราบแน่ชัด ยังคงล้มเหลวแบบปิด เจ้าของที่ถูกแยกจะไม่ย้อนกลับไปใช้แหล่งข้อมูลรับรองที่มีลำดับความสำคัญต่ำกว่า
## การแทรกค่าขณะส่งออก (sentinel)
สำหรับข้อมูลรับรองของผู้ให้บริการโมเดลที่ใช้ SecretRefs เป็นแหล่งข้อมูล OpenClaw จะสร้าง sentinel แบบทึบซึ่งใช้ได้เฉพาะภายในโปรเซส ระหว่างการแก้ค่าการยืนยันตัวตนของโมเดล ดังนั้นพื้นที่จัดเก็บการยืนยันตัวตน ตัวเลือกสตรีม การกำหนดค่า SDK บันทึก ออบเจ็กต์ข้อผิดพลาด และการตรวจสอบรันไทม์ส่วนใหญ่จะเห็นค่าอย่างเช่น `oc-sent-v1-...` แทนข้อมูลรับรองของผู้ให้บริการ การดึงข้อมูลโมเดลที่มีการป้องกันและโพรบตรวจสอบสถานะผู้ให้บริการภายในเครื่องที่มีการจัดการ จะแทนที่ sentinel ที่ทราบในค่า URL และส่วนหัวทันทีก่อนที่แต่ละคำขอจะออกจากโปรเซส
ค่าที่มีรูปแบบเหมือน sentinel แต่ไม่เป็นที่รู้จักจะล้มเหลวแบบปิดก่อนเกิดกิจกรรมเครือข่าย OpenClaw จะปฏิเสธการส่งคำขอแทนการส่งต่อ sentinel ที่ยังไม่ได้แก้ค่าไปยังผู้ให้บริการ ค่าซีเคร็ตที่แก้แล้วจะได้รับการลงทะเบียนเพื่อปกปิดค่าที่ตรงกันทุกประการในบันทึกด้วย เพื่อเป็นมาตรการป้องกันหลายชั้น
อะแดปเตอร์ของผู้ให้บริการใช้จุดแทรกค่าที่ช้าที่สุดซึ่ง SDK รองรับ:
- SDK ที่มีตัวเลือก fetch แบบกำหนดเองจะได้รับ fetch ที่มีการป้องกันของ OpenClaw เพื่อให้ SDK ยังคงเก็บ sentinel ไว้
- SDK ที่ไม่มีตัวเลือก fetch แบบกำหนดเองจะแกะ sentinel ทันทีก่อนสร้างไคลเอนต์ สตรีมผู้ให้บริการที่ Plugin เป็นเจ้าของและชุดควบคุมเอเจนต์จะแกะค่าที่จุดส่งต่อสุดท้ายซึ่ง core เป็นเจ้าของ เนื่องจากการขนส่งเหล่านั้นไม่ได้ใช้ fetch ที่มีการป้องกันของ OpenClaw ร่วมกัน
Sentinel ลดการเปิดเผยข้อความธรรมดาตลอดสายการเรียกโมเดล แต่ไม่ใช่การแยกโปรเซส ค่าจริงยังคงอยู่ในหน่วยความจำของโปรเซสเดียวกันและปรากฏที่ขอบเขตอะแดปเตอร์สุดท้าย ข้อมูลรับรองจากสภาพแวดล้อมแบบธรรมดาที่ไม่ได้กำหนดค่าผ่าน SecretRefs ยังคงเป็นข้อความธรรมดาและอยู่นอกกลไกนี้
ตั้งค่า `OPENCLAW_SECRET_SENTINELS=off` (รองรับ `0` หรือ `false` ด้วย โดยไม่คำนึงถึงตัวพิมพ์เล็ก-ใหญ่) เพื่อปิดการสร้าง sentinel ระหว่างการตอบสนองต่อเหตุการณ์หรือการแก้ไขปัญหาความเข้ากันได้ สวิตช์หยุดฉุกเฉินนี้จะไม่ปิดการลงทะเบียนการปกปิดค่าที่ตรงกันทุกประการ
## ขอบเขตการเข้าถึงของเอเจนต์
SecretRefs ป้องกันไม่ให้ข้อมูลรับรองถูกบันทึกถาวรในการกำหนดค่าและไฟล์โมเดลที่สร้างขึ้น แต่ไม่ใช่ขอบเขตการแยกโปรเซส ข้อมูลรับรองแบบข้อความธรรมดาที่หลงเหลืออยู่บนดิสก์ในพาธที่เอเจนต์อ่านได้ ยังคงอ่านได้ผ่านเครื่องมือไฟล์หรือเชลล์ โดยข้ามการปกปิดระดับ API
สำหรับการใช้งานจริงที่ไฟล์ซึ่งเอเจนต์เข้าถึงได้อยู่ในขอบเขต ให้ถือว่าการย้ายเสร็จสมบูรณ์ก็ต่อเมื่อเป็นไปตามเงื่อนไขทั้งหมดต่อไปนี้:
- ข้อมูลรับรองที่รองรับใช้ SecretRefs แทนค่าข้อความธรรมดา
- ล้างข้อความธรรมดาแบบเก่าที่ตกค้างออกจาก `openclaw.json`, `auth-profiles.json`, `.env` และไฟล์ `models.json` ที่สร้างขึ้นแล้ว
- `openclaw secrets audit --check` ไม่มีสิ่งตกค้างหลังการย้าย
- ข้อมูลรับรองที่เหลือซึ่งยังไม่รองรับหรือมีการหมุนเวียน ต้องได้รับการป้องกันด้วยการแยกระดับระบบปฏิบัติการ การแยกคอนเทนเนอร์ หรือพร็อกซีข้อมูลรับรองภายนอก
นี่คือเหตุผลที่เวิร์กโฟลว์ตรวจสอบ/กำหนดค่า/นำไปใช้เป็นเกตการย้ายด้านความปลอดภัย ไม่ใช่เพียงตัวช่วยอำนวยความสะดวก
SecretRefs ไม่ได้ทำให้ไฟล์ใดๆ ที่อ่านได้มีความปลอดภัย ข้อมูลสำรอง สำเนาการกำหนดค่า แค็ตตาล็อกโมเดลเก่าที่สร้างขึ้น และคลาสข้อมูลรับรองที่ไม่รองรับ ยังคงเป็นซีเคร็ตสำหรับการใช้งานจริงจนกว่าจะถูกลบ ย้ายออกนอกขอบเขตความไว้วางใจของเอเจนต์ หรือแยกออกต่างหาก
## การกรองพื้นผิวที่ใช้งานอยู่
SecretRefs จะได้รับการตรวจสอบเฉพาะบนพื้นผิวที่มีผลใช้งานจริง:
- **พื้นผิวที่เปิดใช้**: ความล้มเหลวที่ลองใหม่ได้สำหรับเจ้าของที่แมปและแยกได้ จะเข้าสู่สถานะลดระดับแบบ cold หรือ stale ความล้มเหลวแบบเข้มงวด แบบล้มเหลวปิด ที่ Gateway จำเป็นต้องใช้ หรือที่ไม่ได้แมป จะบล็อกการเริ่มต้น/โหลดใหม่
- **พื้นผิวที่ไม่ใช้งาน**: การอ้างอิงที่แก้ค่าไม่ได้จะไม่บล็อกการเริ่มต้น/โหลดใหม่ แต่จะแสดงการวินิจฉัย `SECRETS_REF_IGNORED_INACTIVE_SURFACE` ที่ไม่ทำให้ล้มเหลว
- รายการช่องทาง/บัญชีที่ปิดใช้
- ข้อมูลรับรองช่องทางระดับบนสุดที่ไม่มีบัญชีซึ่งเปิดใช้รับช่วง
- พื้นผิวเครื่องมือ/ฟีเจอร์ที่ปิดใช้
- คีย์เฉพาะผู้ให้บริการค้นหาเว็บที่ไม่ได้เลือกโดย `tools.web.search.provider` ในโหมดอัตโนมัติ (ไม่ได้ตั้งค่าผู้ให้บริการ) ระบบจะตรวจสอบคีย์ตามลำดับความสำคัญเพื่อการตรวจหาอัตโนมัติจนกว่าจะมีคีย์หนึ่งแก้ค่าได้ หลังเลือกแล้ว คีย์ของผู้ให้บริการที่ไม่ได้เลือกจะไม่ทำงาน
- ข้อมูลการยืนยันตัวตน sandbox SSH (`agents.defaults.sandbox.ssh.identityData`, `certificateData`, `knownHostsData` รวมถึงค่าที่เขียนทับรายเอเจนต์) จะทำงานเฉพาะเมื่อแบ็กเอนด์ sandbox ที่มีผลคือ `ssh` และโหมด sandbox ไม่ใช่ `off` สำหรับเอเจนต์เริ่มต้นหรือเอเจนต์ที่เปิดใช้
- SecretRefs ของ `gateway.remote.token` / `gateway.remote.password` จะทำงานหากเงื่อนไขใดเงื่อนไขหนึ่งต่อไปนี้เป็นจริง:
- `gateway.mode=remote`
- มีการกำหนดค่า `gateway.remote.url`
- `gateway.tailscale.mode` เป็น `serve` หรือ `funnel`
- ในโหมดภายในเครื่องที่ไม่มีพื้นผิวระยะไกลเหล่านั้น: `gateway.remote.token` จะทำงานเมื่อการยืนยันตัวตนด้วยโทเค็นมีโอกาสถูกเลือกและไม่ได้กำหนดค่าโทเค็นจากสภาพแวดล้อม/การยืนยันตัวตน ส่วน `gateway.remote.password` จะทำงานเฉพาะเมื่อการยืนยันตัวตนด้วยรหัสผ่านมีโอกาสถูกเลือกและไม่ได้กำหนดค่ารหัสผ่านจากสภาพแวดล้อม/การยืนยันตัวตน
- SecretRef ของ `gateway.auth.token` จะไม่ทำงานสำหรับการแก้ค่าการยืนยันตัวตนเมื่อเริ่มต้น หากตั้งค่า `OPENCLAW_GATEWAY_TOKEN` เนื่องจากอินพุตโทเค็นจากสภาพแวดล้อมมีลำดับความสำคัญสูงกว่าสำหรับรันไทม์นั้น
## การวินิจฉัยพื้นผิวการยืนยันตัวตนของ Gateway
เมื่อตั้งค่า SecretRef บน `gateway.auth.token`, `gateway.auth.password`, `gateway.remote.token` หรือ `gateway.remote.password` บันทึกการเริ่มต้น/โหลดใหม่ของ Gateway จะแสดงสถานะพื้นผิวภายใต้รหัส `SECRETS_GATEWAY_AUTH_SURFACE`:
- `active`: SecretRef เป็นส่วนหนึ่งของพื้นผิวการยืนยันตัวตนที่มีผลและต้องแก้ค่าได้
- `inactive`: พื้นผิวการยืนยันตัวตนอื่นมีลำดับความสำคัญสูงกว่า หรือการยืนยันตัวตนระยะไกลถูกปิดใช้/ไม่ทำงาน
รายการบันทึกจะระบุเหตุผลที่นโยบายพื้นผิวที่ใช้งานอยู่เลือกใช้
## การตรวจสอบการอ้างอิงล่วงหน้าระหว่างการเริ่มต้นใช้งาน
ในการเริ่มต้นใช้งานแบบโต้ตอบ การเลือกพื้นที่จัดเก็บ SecretRef จะเรียกใช้การตรวจสอบล่วงหน้าก่อนบันทึก:
- การอ้างอิง Env: ตรวจสอบชื่อของตัวแปรสภาพแวดล้อมและยืนยันว่ามองเห็นค่าที่ไม่ว่างระหว่างการตั้งค่า
- การอ้างอิงผู้ให้บริการ (`file` หรือ `exec`): ตรวจสอบการเลือกผู้ให้บริการ แก้ค่า `id` และตรวจสอบชนิดของค่าที่แก้แล้ว
- ขั้นตอนเริ่มต้นด่วน: เมื่อ `gateway.auth.token` เป็น SecretRef อยู่แล้ว การเริ่มต้นใช้งานจะแก้ค่าก่อนเริ่มโพรบ/แดชบอร์ด (สำหรับการอ้างอิง `env`, `file` และ `exec`) โดยใช้เกตที่ล้มเหลวทันทีแบบเดียวกัน
หากการตรวจสอบล้มเหลว ระบบจะแสดงข้อผิดพลาดและให้ลองใหม่ได้
## สัญญา SecretRef
ใช้รูปแบบออบเจ็กต์เดียวกันทุกที่:
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
```
```json5
{ source: "env", provider: "default", id: "OPENAI_API_KEY" }
```
ฟิลด์ SecretInput รองรับสตริงรูปแบบย่อด้วย:
```json5
"${OPENAI_API_KEY}"
"$OPENAI_API_KEY"
```
การตรวจสอบ:
- `provider` ต้องตรงกับ `^[a-z][a-z0-9_-]{0,63}$`
- `id` ต้องตรงกับ `^[A-Z][A-Z0-9_]{0,127}$`
```json5
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
```
การตรวจสอบ:
- `provider` ต้องตรงกับ `^[a-z][a-z0-9_-]{0,63}$`
- `id` ต้องเป็นตัวชี้ JSON แบบสัมบูรณ์ (`/...`) หรือเป็นค่าตรงตัว `value` สำหรับผู้ให้บริการ `singleValue`
- การหลีกอักขระตาม RFC 6901 ในแต่ละเซกเมนต์: `~` จะกลายเป็น `~0`, `/` จะกลายเป็น `~1`
```json5
{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }
```
การตรวจสอบ:
- `provider` ต้องตรงกับ `^[a-z][a-z0-9_-]{0,63}$`
- `id` ต้องตรงกับ `^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$` (รองรับตัวเลือก เช่น `secret#json_key`)
- `id` ต้องไม่มี `.` หรือ `..` เป็นเซกเมนต์พาธที่คั่นด้วยเครื่องหมายทับ (ตัวอย่างเช่น `a/../b` จะถูกปฏิเสธ)
## การกำหนดค่าผู้ให้บริการ
กำหนดผู้ให้บริการภายใต้ `secrets.providers`:
```json5
{
secrets: {
providers: {
default: { source: "env" },
filemain: {
source: "file",
path: "~/.openclaw/secrets.json",
mode: "json", // หรือ "singleValue"
},
vault: {
source: "exec",
command: "/usr/local/bin/openclaw-vault-resolver",
args: ["--profile", "prod"],
passEnv: ["PATH", "VAULT_ADDR"],
jsonOnly: true,
},
"team-secrets": {
source: "exec",
pluginIntegration: {
pluginId: "acme-secrets",
integrationId: "secret-store",
},
},
},
defaults: {
env: "default",
file: "filemain",
exec: "vault",
},
},
}
```
- รายการอนุญาตชื่อที่ตรงกันทุกประการซึ่งเป็นตัวเลือก ผ่าน `allowlist`
- ค่า env ที่ไม่มีหรือว่างจะทำให้การแก้ค่าล้มเหลว
- อ่านไฟล์ภายในเครื่องที่ `path`
- `mode: "json"` (ค่าเริ่มต้น) คาดหวังเพย์โหลดออบเจ็กต์ JSON และแก้ค่า `id` เป็นตัวชี้ JSON
- `mode: "singleValue"` คาดหวังรหัสการอ้างอิง `"value"` และคืนค่าเนื้อหาไฟล์ดิบ (ตัดอักขระขึ้นบรรทัดใหม่ท้ายไฟล์ออก)
- พาธต้องผ่านการตรวจสอบเจ้าของ/สิทธิ์ โดย `timeoutMs` (ค่าเริ่มต้น 5000) และ `maxBytes` (ค่าเริ่มต้น 1 MiB) จะจำกัดการอ่าน
- Windows จะล้มเหลวแบบปิด: หากไม่สามารถตรวจสอบ ACL สำหรับพาธได้ การแก้ค่าจะล้มเหลว สำหรับพาธที่เชื่อถือได้เท่านั้น ให้ตั้งค่า `allowInsecurePath: true` บนผู้ให้บริการนั้นเพื่อข้ามการตรวจสอบ
- เรียกใช้พาธไบนารีแบบสัมบูรณ์ที่กำหนดค่าไว้โดยตรง โดยไม่ใช้เชลล์
- โดยค่าเริ่มต้น `command` ต้องเป็นไฟล์ปกติ ไม่ใช่ลิงก์สัญลักษณ์ ตั้งค่า `allowSymlinkCommand: true` เพื่ออนุญาตพาธคำสั่งที่เป็นลิงก์สัญลักษณ์ (เช่น ชิมของ Homebrew) และใช้ร่วมกับ `trustedDirs` (เช่น `["/opt/homebrew"]`) เพื่อให้เฉพาะพาธของตัวจัดการแพ็กเกจเท่านั้นที่ผ่านเกณฑ์
- รองรับ `timeoutMs` (ค่าเริ่มต้น 5000), `noOutputTimeoutMs` (ค่าเริ่มต้นเท่ากับ `timeoutMs`), `maxOutputBytes` (ค่าเริ่มต้น 1 MiB), รายการอนุญาต `env`/`passEnv` และ `trustedDirs`
- `jsonOnly` มีค่าเริ่มต้นเป็น `true` เมื่อใช้ `jsonOnly: false` และร้องขอเพียง id เดียว ระบบจะยอมรับ stdout แบบข้อความธรรมดาที่ไม่ใช่ JSON เป็นค่าของ id นั้น
- Windows จะปฏิเสธโดยอัตโนมัติเมื่อไม่สามารถยืนยันความปลอดภัยได้: หากไม่สามารถตรวจสอบ ACL ของพาธคำสั่งได้ การแก้ไขค่าจะล้มเหลว สำหรับพาธที่เชื่อถือได้เท่านั้น ให้ตั้งค่า `allowInsecurePath: true` ในผู้ให้บริการนั้นเพื่อข้ามการตรวจสอบ
- ผู้ให้บริการ exec ที่ Plugin จัดการสามารถใช้ `pluginIntegration` แทน `command`/`args` ที่คัดลอกมาได้ OpenClaw จะแก้ไขรายละเอียดคำสั่งปัจจุบันจากไฟล์ manifest ของ Plugin ที่ติดตั้งไว้ระหว่างการเริ่มต้น/โหลดซ้ำ หาก Plugin ถูกปิดใช้งาน ถูกนำออก ไม่น่าเชื่อถือ หรือไม่ได้ประกาศการผสานรวมนี้อีกต่อไป SecretRef ที่ใช้งานอยู่ในผู้ให้บริการนั้นจะปฏิเสธโดยอัตโนมัติเมื่อไม่สามารถยืนยันความปลอดภัยได้
เพย์โหลดคำขอ (stdin):
```json
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }
```
เพย์โหลดการตอบกลับ (stdout):
```jsonc
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "" } } // pragma: รายการอนุญาตข้อมูลลับ
```
ข้อผิดพลาดแยกตาม id ซึ่งระบุหรือไม่ก็ได้:
```json
{
"protocolVersion": 1,
"values": {},
"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }
}
```
`code` เป็นข้อมูลวินิจฉัยที่เครื่องอ่านได้ซึ่งระบุหรือไม่ก็ได้ OpenClaw แสดง
รหัสที่รู้จัก ได้แก่ `NOT_FOUND` และ `AMBIGUOUS_DUPLICATE_KEY` พร้อมผู้ให้บริการและ ref id ส่วนรหัสอื่น
และฟิลด์รูปแบบอิสระ เช่น `message` จะได้รับการยอมรับเพื่อให้เข้ากันได้กับ protocol-v1
แต่จะไม่แสดง เนื่องจากเอาต์พุตของตัวแก้ไขค่าอาจมีข้อมูลรับรองอยู่
## คีย์ API ที่จัดเก็บในไฟล์
อย่าใส่สตริง `file:...` ในบล็อก `env` ของการกำหนดค่า บล็อกนั้นเป็นค่าตามตัวอักษรและไม่เขียนทับค่าอื่น ดังนั้น `file:...` จะไม่ได้รับการแก้ไขค่าในบล็อกนั้น
ให้ใช้ SecretRef แบบไฟล์ในฟิลด์ข้อมูลรับรองที่รองรับแทน:
```json5
{
secrets: {
providers: {
xai_key_file: {
source: "file",
path: "~/.openclaw/secrets/xai-api-key.txt",
mode: "singleValue",
},
},
},
models: {
providers: {
xai: {
apiKey: { source: "file", provider: "xai_key_file", id: "value" },
},
},
},
}
```
สำหรับ `mode: "singleValue"` ค่า `id` ของ SecretRef คือ `"value"` สำหรับ `mode: "json"` ให้ใช้ตัวชี้ JSON แบบสัมบูรณ์ เช่น `"/providers/xai/apiKey"`
ดูฟิลด์ที่ยอมรับ SecretRef ได้ที่ [พื้นผิวข้อมูลรับรอง SecretRef](/th/reference/secretref-credential-surface)
## ตัวอย่างการผสานรวม Exec
สำหรับคู่มือ 1Password โดยเฉพาะ ซึ่งครอบคลุมบัญชีบริการ Skills ของเอเจนต์ที่รวมมาให้ และการแก้ไขปัญหา โปรดดู [1Password](/th/gateway/1password)
```json5
{
secrets: {
providers: {
onepassword_openai: {
source: "exec",
command: "/opt/homebrew/bin/op",
allowSymlinkCommand: true, // จำเป็นสำหรับไบนารีที่ Homebrew เชื่อมโยงด้วยลิงก์สัญลักษณ์
trustedDirs: ["/opt/homebrew"],
args: ["read", "op://Personal/OpenClaw QA API Key/password"],
passEnv: ["HOME"],
jsonOnly: false,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
},
},
},
}
```
ใช้แรปเปอร์ตัวแก้ไขค่าเพื่อจับคู่ id ของ SecretRef กับคีย์รายการใน Bitwarden Secrets Manager รีโพซิทอรีมี `scripts/secrets/openclaw-bws-resolver.mjs` รวมอยู่ด้วย ให้ติดตั้งหรือคัดลอกไปยังพาธสัมบูรณ์ที่เชื่อถือได้บนโฮสต์ซึ่งเรียกใช้ Gateway
ข้อกำหนด:
- ติดตั้ง CLI ของ Bitwarden Secrets Manager (`bws`) บนโฮสต์ของ Gateway
- บริการ Gateway สามารถเข้าถึง `BWS_ACCESS_TOKEN` ได้
- ส่ง `PATH` ให้ตัวแก้ไขค่า หรือตั้งค่า `BWS_BIN` เป็นพาธสัมบูรณ์ของไบนารี `bws`
- ตั้งค่า `BWS_SERVER_URL` ในสภาพแวดล้อมเมื่อใช้อินสแตนซ์ Bitwarden ที่โฮสต์เอง
```json5
{
secrets: {
providers: {
bws: {
source: "exec",
command: "/usr/local/bin/openclaw-bws-resolver.mjs",
passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],
jsonOnly: true,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: {
source: "exec",
provider: "bws",
id: "openclaw/providers/openai/apiKey",
},
},
},
},
}
```
ตัวแก้ไขค่าจะประมวลผล id ที่ร้องขอเป็นชุด เรียกใช้ `bws secret list` และส่งคืนค่าของฟิลด์ `key` ในข้อมูลลับที่ตรงกัน ใช้คีย์ที่เป็นไปตามข้อกำหนด id ของ exec SecretRef เช่น `openclaw/providers/openai/apiKey` โดยคีย์รูปแบบตัวแปรสภาพแวดล้อมที่มีขีดล่างจะถูกปฏิเสธก่อนเรียกใช้ตัวแก้ไขค่า หากข้อมูลลับ Bitwarden ที่มองเห็นได้มากกว่าหนึ่งรายการใช้คีย์ที่ร้องขอร่วมกัน ตัวแก้ไขค่าจะรายงานว่า id นั้นกำกวมและล้มเหลวแทนการคาดเดา หลังอัปเดตการกำหนดค่าแล้ว ให้ตรวจสอบพาธของตัวแก้ไขค่า:
```bash
openclaw secrets audit --allow-exec
```
```json5
{
secrets: {
providers: {
vault_openai: {
source: "exec",
command: "/opt/homebrew/bin/vault",
allowSymlinkCommand: true, // จำเป็นสำหรับไบนารีที่ Homebrew เชื่อมโยงด้วยลิงก์สัญลักษณ์
trustedDirs: ["/opt/homebrew"],
args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
jsonOnly: false,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: { source: "exec", provider: "vault_openai", id: "value" },
},
},
},
}
```
ใช้แรปเปอร์ตัวแก้ไขค่าขนาดเล็กเพื่อจับคู่ id ของ SecretRef กับรายการ `pass` โดยตรง บันทึกไฟล์นี้เป็นไฟล์ปฏิบัติการในพาธสัมบูรณ์ที่ผ่านการตรวจสอบพาธของผู้ให้บริการ exec เช่น `/usr/local/bin/openclaw-pass-resolver` shebang `#!/usr/bin/env node` จะแก้ไขค่า `node` จาก `PATH` ของกระบวนการตัวแก้ไขค่า ดังนั้นให้รวม `PATH` ไว้ใน `passEnv` หาก `pass` ไม่อยู่ใน `PATH` นั้น ให้ตั้งค่า `PASS_BIN` ในสภาพแวดล้อมแม่และรวมไว้ใน `passEnv` ด้วย:
```js
#!/usr/bin/env node
const { spawnSync } = require("node:child_process");
let stdin = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
stdin += chunk;
});
process.stdin.on("error", (err) => {
process.stderr.write(`${err.message}\n`);
process.exit(1);
});
process.stdin.on("end", () => {
let request;
try {
request = JSON.parse(stdin || "{}");
} catch (err) {
process.stderr.write(`แยกวิเคราะห์คำขอไม่สำเร็จ: ${err.message}\n`);
process.exit(1);
}
const passBin = process.env.PASS_BIN || "pass";
const values = {};
const errors = {};
for (const id of request.ids ?? []) {
const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });
if (result.status === 0) {
values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";
} else {
errors[id] = { message: (result.stderr || `pass ออกจากการทำงานด้วยสถานะ ${result.status}`).trim() };
}
}
process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));
});
```
จากนั้นกำหนดค่าผู้ให้บริการ exec และชี้ `apiKey` ไปยังพาธรายการ `pass`:
```json5
{
secrets: {
providers: {
pass_store: {
source: "exec",
command: "/usr/local/bin/openclaw-pass-resolver",
passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],
jsonOnly: true,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: {
source: "exec",
provider: "pass_store",
id: "openclaw/providers/openai/apiKey",
},
},
},
},
}
```
เก็บข้อมูลลับไว้ในบรรทัดแรกของรายการ `pass` หรือปรับแต่งแรปเปอร์ให้ส่งคืนเอาต์พุต `pass show` ทั้งหมดแทน หลังอัปเดตการกำหนดค่าแล้ว ให้ตรวจสอบทั้งการตรวจสอบแบบคงที่และพาธของตัวแก้ไขค่า exec:
```bash
openclaw secrets audit --check
openclaw secrets audit --allow-exec
```
```json5
{
secrets: {
providers: {
sops_openai: {
source: "exec",
command: "/opt/homebrew/bin/sops",
allowSymlinkCommand: true, // จำเป็นสำหรับไบนารีที่ Homebrew เชื่อมโยงด้วยลิงก์สัญลักษณ์
trustedDirs: ["/opt/homebrew"],
args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
passEnv: ["SOPS_AGE_KEY_FILE"],
jsonOnly: false,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: { source: "exec", provider: "sops_openai", id: "value" },
},
},
},
}
```
## ตัวแปรสภาพแวดล้อมของเซิร์ฟเวอร์ MCP
ตัวแปรสภาพแวดล้อมของเซิร์ฟเวอร์ MCP ที่กำหนดค่าผ่าน `plugins.entries.acpx.config.mcpServers` ยอมรับ SecretInput ซึ่งช่วยไม่ให้คีย์ API และโทเค็นอยู่ในการกำหนดค่าแบบข้อความธรรมดา:
```json5
{
plugins: {
entries: {
acpx: {
enabled: true,
config: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_PERSONAL_ACCESS_TOKEN: {
source: "env",
provider: "default",
id: "MCP_GITHUB_PAT",
},
},
},
},
},
},
},
},
}
```
ค่าสตริงแบบข้อความธรรมดายังคงใช้งานได้ การอ้างอิงเทมเพลตตัวแปรสภาพแวดล้อม เช่น `${MCP_SERVER_API_KEY}` และออบเจ็กต์ SecretRef จะได้รับการแก้ไขค่าระหว่างการเปิดใช้งาน Gateway ก่อนเริ่มกระบวนการเซิร์ฟเวอร์ MCP เช่นเดียวกับพื้นผิว SecretRef อื่น การอ้างอิงที่แก้ไขค่าไม่ได้จะขัดขวางการเปิดใช้งานเฉพาะเมื่อ Plugin `acpx` มีสถานะใช้งานจริงเท่านั้น
## ข้อมูลยืนยันตัวตน SSH สำหรับ Sandbox
แบ็กเอนด์ Sandbox หลัก `ssh` รองรับ SecretRef สำหรับข้อมูลยืนยันตัวตน SSH ด้วย:
```json5
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "ssh",
ssh: {
target: "user@gateway-host:22",
identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
},
},
},
},
}
```
พฤติกรรมขณะรันไทม์:
- OpenClaw แก้ไขการอ้างอิงเหล่านี้ระหว่างการเปิดใช้งานแซนด์บ็อกซ์ ไม่ใช่แบบหน่วงเวลาในแต่ละครั้งที่เรียกใช้ SSH
- ค่าที่แก้ไขแล้วจะถูกเขียนลงในไดเรกทอรีชั่วคราวโดยมีสิทธิ์เข้าถึงไฟล์ที่เข้มงวด (`0o600`) และใช้ในคอนฟิก SSH ที่สร้างขึ้น
- หากแบ็กเอนด์แซนด์บ็อกซ์ที่มีผลไม่ใช่ `ssh` (หรือโหมดแซนด์บ็อกซ์เป็น `off`) การอ้างอิงเหล่านี้จะยังไม่ทำงานและไม่ขัดขวางการเริ่มต้นระบบ
## พื้นผิวข้อมูลประจำตัวที่รองรับ
ข้อมูลประจำตัวที่รองรับและไม่รองรับตามมาตรฐานแสดงอยู่ใน [พื้นผิวข้อมูลประจำตัว SecretRef](/th/reference/secretref-credential-surface)
ข้อมูลประจำตัวที่สร้างขึ้นขณะรันไทม์หรือมีการหมุนเวียน และข้อมูลสำหรับรีเฟรช OAuth ถูกยกเว้นจากการแก้ไข SecretRef แบบอ่านอย่างเดียวโดยเจตนา
## พฤติกรรมและลำดับความสำคัญที่กำหนด
- ฟิลด์ที่ไม่มีการอ้างอิง: ไม่เปลี่ยนแปลง
- ฟิลด์ที่มีการอ้างอิง: ต้องพร้อมใช้งานบนพื้นผิวที่ทำงานอยู่ระหว่างการเปิดใช้งาน
- หากมีทั้งข้อความธรรมดาและการอ้างอิง การอ้างอิงจะมีลำดับความสำคัญสูงกว่าในเส้นทางลำดับความสำคัญที่รองรับ
- ค่าตัวแทนการปกปิด `__OPENCLAW_REDACTED__` สงวนไว้สำหรับการปกปิด/คืนค่าคอนฟิกภายใน และจะถูกปฏิเสธหากส่งมาเป็นข้อมูลคอนฟิกตามตัวอักษร
สัญญาณคำเตือนและการตรวจสอบ:
- `SECRETS_REF_OVERRIDES_PLAINTEXT` (คำเตือนขณะรันไทม์)
- `REF_SHADOWED` (ข้อค้นพบจากการตรวจสอบเมื่อข้อมูลประจำตัว `auth-profiles.json` มีลำดับความสำคัญเหนือการอ้างอิง `openclaw.json`)
ความเข้ากันได้กับ Google Chat: `serviceAccountRef` มีลำดับความสำคัญเหนือข้อความธรรมดา `serviceAccount`; ค่าข้อความธรรมดาจะถูกละเว้นเมื่อตั้งค่าการอ้างอิงระดับเดียวกันแล้ว
## ตัวกระตุ้นการเปิดใช้งาน
การเปิดใช้งานข้อมูลลับจะทำงานเมื่อ:
- เริ่มต้นระบบ (การตรวจสอบก่อนดำเนินการร่วมกับการเปิดใช้งานขั้นสุดท้าย)
- เส้นทางใช้การเปลี่ยนแปลงคอนฟิกแบบทันทีเมื่อโหลดใหม่
- เส้นทางตรวจสอบการรีสตาร์ตเมื่อโหลดคอนฟิกใหม่
- โหลดใหม่ด้วยตนเองผ่าน `secrets.reload`
- การตรวจสอบก่อนดำเนินการของ RPC สำหรับเขียนคอนฟิก Gateway (`config.set` / `config.apply` / `config.patch`) ซึ่งตรวจสอบ SecretRef บนพื้นผิวที่ทำงานอยู่ภายในเพย์โหลดคอนฟิกที่ส่งมา ก่อนบันทึกการแก้ไขอย่างถาวร
สัญญาการเปิดใช้งาน:
- เมื่อสำเร็จ ระบบจะสลับสแนปช็อตแบบอะตอมมิก
- ความล้มเหลวแบบเข้มงวดระหว่างการเริ่มต้นจะยกเลิกการเริ่มต้น Gateway
- ระหว่างการเริ่มต้นแบบเย็น ความล้มเหลวในการแก้ไขที่ลองใหม่ได้สำหรับเจ้าของที่ไม่ใช่ Gateway ซึ่งมีการแมปและแยกได้ อาจเผยแพร่สแนปช็อตโดยตั้งค่าเฉพาะเจ้าของรายนั้นว่าไม่พร้อมใช้งานตามคอนฟิก คำขอสำหรับเจ้าของจะล้มเหลวด้วย `SECRET_SURFACE_UNAVAILABLE`; เจ้าของผู้ให้บริการโมเดลจะไม่ถอยกลับไปใช้ข้อมูลประจำตัวจากสภาพแวดล้อมหรือโปรไฟล์การตรวจสอบสิทธิ์ หลังจากการอ้างอิงที่ระบุไว้อย่างชัดเจนล้มเหลว
- การโหลดใหม่และการตรวจสอบการรีสตาร์ตจะแยกเจ้าของที่มีสิทธิ์และมีการแมป เอกลักษณ์การอ้างอิงที่ไม่เปลี่ยนแปลง ซึ่งมีนิยามผู้ให้บริการไม่เปลี่ยนแปลงและสัญญาเจ้าของที่ครบถ้วนซึ่งไม่ใช่ข้อมูลลับไม่เปลี่ยนแปลง จะคงค่าที่ทราบว่าดีล่าสุดไว้ตามเดิมในสถานะเก่า; การอ้างอิงที่เปลี่ยนแปลงหรือกำหนดค่าใหม่แต่แก้ไขไม่ได้จะเผยแพร่แบบเย็นเฉพาะเจ้าของรายนั้น ความล้มเหลวแบบเข้มงวดระหว่างการโหลดใหม่จะคงสแนปช็อตที่ทำงานอยู่ก่อนหน้าไว้
- `config.set`, `config.apply` และ `config.patch` ยอมรับการอ้างอิงที่ยังแก้ไขไม่ได้แต่ถูกต้องตามไวยากรณ์สำหรับเจ้าของที่แยกได้ และส่งคืนรายงาน `degradedSecretOwners` ที่ปกปิดข้อมูลแล้ว การตรวจสอบสิทธิ์ขาเข้าของ Gateway, คอนฟิกหรือค่าที่แก้ไขแล้วซึ่งไม่ถูกต้องเชิงโครงสร้าง, การละเมิดนโยบาย และเจ้าของที่ไม่รู้จัก ยังคงถูกปฏิเสธก่อนแก้ไขดิสก์
- เจ้าของระดับเดียวกันที่มีสถานะปกติจะแก้ไขและเผยแพร่ตามปกติ แม้เจ้าของรายอื่นจะอยู่ในสถานะเย็นหรือเก่า
- การระบุโทเค็นช่องทางแยกสำหรับแต่ละครั้งอย่างชัดเจนให้กับการเรียกตัวช่วย/เครื่องมือขาออก จะไม่กระตุ้นการเปิดใช้งาน SecretRef; จุดเปิดใช้งานยังคงเป็นการเริ่มต้น การโหลดใหม่ และ `secrets.reload` ที่เรียกอย่างชัดเจน
## สัญญาณสถานะเสื่อมและกู้คืนแล้ว
เมื่อการเปิดใช้งานระหว่างโหลดใหม่ล้มเหลวหลังจากอยู่ในสถานะปกติ OpenClaw จะเข้าสู่สถานะข้อมูลลับเสื่อม พร้อมส่งเหตุการณ์ระบบแบบครั้งเดียวและรหัสบันทึก:
- `SECRETS_RELOADER_DEGRADED`
- `SECRETS_RELOADER_RECOVERED`
พฤติกรรม:
- สถานะเสื่อม: เจ้าของที่มีสถานะปกติจะรีเฟรช เจ้าของที่อยู่ในสถานะเก่าจะคงค่าที่ทราบว่าดีล่าสุดไว้ และเจ้าของที่อยู่ในสถานะเย็นจะยังไม่พร้อมใช้งาน
- กู้คืนแล้ว: ส่งหนึ่งครั้งหลังการเปิดใช้งานครั้งถัดไปสำเร็จ
- ความล้มเหลวซ้ำขณะที่อยู่ในสถานะเสื่อมแล้วจะบันทึกคำเตือน แต่ไม่ส่งเหตุการณ์ซ้ำ
- ความล้มเหลวแบบเข้มงวดระหว่างการเริ่มต้นจะไม่ส่งเหตุการณ์สถานะเสื่อม เนื่องจากรันไทม์ไม่เคยทำงาน การเริ่มต้นที่สำเร็จแต่มีเจ้าของอยู่ในสถานะเย็นจะบันทึกการเสื่อมของเจ้าของ แต่ไม่ส่งเหตุการณ์ของตัวโหลดใหม่
- ความล้มเหลวระหว่างการเริ่มต้นและโหลดใหม่ในขอบเขตการอ้างอิงจะส่งคำเตือน `SECRETS_DEGRADED` แบบมีโครงสร้างสำหรับเจ้าของแต่ละรายที่ได้รับผลกระทบ การหยุดให้บริการในขอบเขตผู้ให้บริการจะส่งคำเตือน `SECRETS_PROVIDER_DEGRADED` หนึ่งรายการ พร้อมผู้ให้บริการและรายชื่อเจ้าของที่ได้รับผลกระทบทั้งหมด แทนการแจ้งความล้มเหลวของผู้ให้บริการซ้ำสำหรับเจ้าของแต่ละราย คำเตือนประกอบด้วยเหตุผลที่ปกปิดข้อมูลแล้ว สถานะเจ้าของ `cold` หรือ `stale` และคำแนะนำให้ลองใหม่ `openclaw secrets reload` คำเตือนจะไม่รวมค่าที่แก้ไขแล้วหรือรหัส SecretRef
- `openclaw doctor` แสดงรายชื่อเจ้าของที่อยู่ในสถานะเย็นและเก่า พร้อมเส้นทางคอนฟิกที่ได้รับผลกระทบ เหตุผลที่ปกปิดข้อมูลแล้ว และคำแนะนำในการลองใหม่
## การแก้ไขเส้นทางคำสั่ง
เส้นทางคำสั่งสามารถเลือกรับการแก้ไข SecretRef ที่รองรับผ่าน RPC สแนปช็อตของ Gateway ได้ โดยมีพฤติกรรมหลักสองแบบ:
ตัวอย่างเช่น เส้นทางหน่วยความจำระยะไกล `openclaw memory` และ `openclaw qr --remote` เมื่อต้องใช้การอ้างอิงข้อมูลลับร่วมระยะไกล เส้นทางเหล่านี้อ่านจากสแนปช็อตที่ทำงานอยู่และล้มเหลวทันทีเมื่อ SecretRef ที่จำเป็นไม่พร้อมใช้งาน
ตัวอย่างเช่น `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve`, `openclaw security audit` และโฟลว์ doctor/ซ่อมแซมคอนฟิกแบบอ่านอย่างเดียว เส้นทางเหล่านี้ให้ความสำคัญกับสแนปช็อตที่ทำงานอยู่เช่นกัน แต่จะลดระดับการทำงานแทนการยกเลิกเมื่อ SecretRef เป้าหมายไม่พร้อมใช้งาน
พฤติกรรมแบบอ่านอย่างเดียว:
- เมื่อ Gateway กำลังทำงาน คำสั่งเหล่านี้จะอ่านจากสแนปช็อตที่ทำงานอยู่ก่อน
- หากการแก้ไขของ Gateway ไม่สมบูรณ์หรือ Gateway ไม่พร้อมใช้งาน ระบบจะพยายามใช้ทางเลือกสำรองภายในแบบเจาะจงสำหรับพื้นผิวคำสั่งนั้น
- หาก SecretRef เป้าหมายยังไม่พร้อมใช้งาน คำสั่งจะทำงานต่อด้วยผลลัพธ์แบบอ่านอย่างเดียวที่ลดระดับ และข้อความวินิจฉัยอย่างชัดเจนว่าการอ้างอิงได้รับการกำหนดค่าแล้ว แต่ไม่พร้อมใช้งานในเส้นทางคำสั่งนี้
- พฤติกรรมที่ลดระดับนี้จำกัดอยู่เฉพาะคำสั่งเท่านั้น และไม่ลดความเข้มงวดของการเริ่มต้นรันไทม์ การโหลดใหม่ หรือเส้นทางส่ง/ตรวจสอบสิทธิ์
หมายเหตุอื่นๆ:
- การรีเฟรชสแนปช็อตหลังการหมุนเวียนข้อมูลลับของแบ็กเอนด์ดำเนินการโดย `openclaw secrets reload`
- เมธอด RPC ของ Gateway ที่เส้นทางคำสั่งเหล่านี้ใช้: `secrets.resolve`
## เวิร์กโฟลว์การตรวจสอบและกำหนดค่า
โฟลว์เริ่มต้นสำหรับผู้ปฏิบัติงาน:
```bash
openclaw secrets audit --check
```
```bash
openclaw secrets configure --apply
```
```bash
openclaw secrets audit --check
```
อย่าถือว่าการย้ายข้อมูลเสร็จสมบูรณ์จนกว่าการตรวจสอบซ้ำจะไม่พบปัญหา หากการตรวจสอบยังรายงานค่าข้อความธรรมดาที่จัดเก็บอยู่ ความเสี่ยงที่เอเจนต์จะเข้าถึงยังคงอยู่ แม้ API ขณะรันไทม์จะส่งคืนค่าที่ปกปิดข้อมูลแล้วก็ตาม
หากบันทึกแผนแทนการใช้แผนระหว่าง `configure` ให้ใช้แผนที่บันทึกไว้นั้นด้วย `openclaw secrets apply --from ` ก่อนตรวจสอบซ้ำ
ข้อค้นพบประกอบด้วย:
- ค่าข้อความธรรมดาที่จัดเก็บอยู่ (`openclaw.json`, `auth-profiles.json`, `.env` และ `agents/*/agent/models.json` ที่สร้างขึ้น)
- ข้อมูลตกค้างของส่วนหัวผู้ให้บริการที่ละเอียดอ่อนในรายการ `models.json` ที่สร้างขึ้น
- การอ้างอิงที่ยังแก้ไขไม่ได้
- การบดบังตามลำดับความสำคัญ (`auth-profiles.json` มีลำดับความสำคัญเหนือการอ้างอิง `openclaw.json`)
- ข้อมูลตกค้างแบบเก่า (`auth.json`, การแจ้งเตือน OAuth)
หมายเหตุเกี่ยวกับ Exec: โดยค่าเริ่มต้น การตรวจสอบจะข้ามการตรวจสอบความสามารถในการแก้ไข SecretRef แบบ exec เพื่อหลีกเลี่ยงผลข้างเคียงจากคำสั่ง ใช้ `openclaw secrets audit --allow-exec` เพื่อเรียกใช้ผู้ให้บริการ exec ระหว่างการตรวจสอบ
หมายเหตุเกี่ยวกับข้อมูลตกค้างในส่วนหัว: การตรวจหาส่วนหัวผู้ให้บริการที่ละเอียดอ่อนอิงตามการอนุมานจากชื่อ (ชื่อและส่วนของชื่อส่วนหัวที่ใช้ทั่วไปสำหรับการตรวจสอบสิทธิ์/ข้อมูลประจำตัว เช่น `authorization`, `x-api-key`, `token`, `secret`, `password` และ `credential`)
ตัวช่วยแบบโต้ตอบที่:
- กำหนดค่า `secrets.providers` ก่อน (`env`/`file`/`exec`, เพิ่ม/แก้ไข/ลบ)
- ให้เลือกฟิลด์ที่รองรับและมีข้อมูลลับใน `openclaw.json` รวมถึง `auth-profiles.json` สำหรับขอบเขตเอเจนต์หนึ่งรายการ
- สามารถสร้างการแมป `auth-profiles.json` ใหม่ได้โดยตรงในตัวเลือกเป้าหมาย
- เก็บรายละเอียด SecretRef (`source`, `provider`, `id`)
- เรียกใช้การแก้ไขก่อนดำเนินการและสามารถใช้การเปลี่ยนแปลงได้ทันที
หมายเหตุเกี่ยวกับ Exec: การตรวจสอบก่อนดำเนินการจะข้ามการตรวจสอบ SecretRef แบบ exec เว้นแต่ตั้งค่า `--allow-exec` หากใช้แผนโดยตรงจาก `configure --apply` และแผนมีการอ้างอิง/ผู้ให้บริการแบบ exec ให้คงการตั้งค่า `--allow-exec` ไว้สำหรับขั้นตอนการใช้แผนด้วย
โหมดที่มีประโยชน์:
- `openclaw secrets configure --providers-only`
- `openclaw secrets configure --skip-provider-setup`
- `openclaw secrets configure --agent `
ค่าเริ่มต้นของการใช้ `configure`:
- ล้างข้อมูลประจำตัวแบบคงที่ที่ตรงกันออกจาก `auth-profiles.json` สำหรับผู้ให้บริการเป้าหมาย
- ล้างรายการ `api_key` แบบคงที่รุ่นเก่าออกจาก `auth.json`
- ล้างบรรทัดข้อมูลลับที่รู้จักและตรงกันออกจากไฟล์ `.env` ของสถานะที่มีผลและคอนฟิกที่ทำงานอยู่ (ขจัดรายการซ้ำเมื่อทั้งสองเส้นทางตรงกัน)
ใช้แผนที่บันทึกไว้:
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
```
หมายเหตุเกี่ยวกับ Exec: การทดลองทำงานจะข้ามการตรวจสอบ exec เว้นแต่ตั้งค่า `--allow-exec`; โหมดเขียนจะปฏิเสธแผนที่มี SecretRef/ผู้ให้บริการแบบ exec เว้นแต่ตั้งค่า `--allow-exec`
สำหรับรายละเอียดสัญญาเป้าหมาย/เส้นทางแบบเข้มงวดและกฎการปฏิเสธที่แน่นอน โปรดดู [สัญญาแผนการใช้ข้อมูลลับ](/th/gateway/secrets-plan-contract)
## นโยบายความปลอดภัยทางเดียว
OpenClaw ไม่เขียนข้อมูลสำรองสำหรับย้อนกลับที่มีค่าข้อมูลลับแบบข้อความธรรมดาในอดีตโดยเจตนา
แบบจำลองความปลอดภัย:
- การตรวจสอบก่อนดำเนินการต้องสำเร็จก่อนเข้าสู่โหมดเขียน
- ระบบจะตรวจสอบการเปิดใช้งานรันไทม์ก่อนยืนยันการเปลี่ยนแปลง
- การใช้แผนจะอัปเดตไฟล์ด้วยการแทนที่ไฟล์แบบอะตอมมิก และพยายามคืนค่าอย่างเต็มความสามารถเมื่อล้มเหลว
## หมายเหตุความเข้ากันได้กับการตรวจสอบสิทธิ์รุ่นเก่า
สำหรับข้อมูลประจำตัวแบบคงที่ รันไทม์ไม่ต้องพึ่งพาพื้นที่จัดเก็บการตรวจสอบสิทธิ์รุ่นเก่าที่เป็นข้อความธรรมดาอีกต่อไป
- แหล่งข้อมูลประจำตัวของรันไทม์คือสแนปช็อตในหน่วยความจำที่แก้ไขแล้ว
- รายการ `api_key` แบบคงที่รุ่นเก่าจะถูกล้างเมื่อตรวจพบ
- พฤติกรรมความเข้ากันได้ที่เกี่ยวข้องกับ OAuth ยังคงแยกต่างหาก
## หมายเหตุเกี่ยวกับ Web UI
ยูเนียน SecretInput บางรายการกำหนดค่าในโหมดตัวแก้ไขข้อมูลดิบได้ง่ายกว่าโหมดฟอร์ม
## ที่เกี่ยวข้อง
- [การยืนยันตัวตน](/th/gateway/authentication) - การตั้งค่าการยืนยันตัวตน
- [CLI: ข้อมูลลับ](/th/cli/secrets) - คำสั่ง CLI
- [SecretRefs ของ Vault](/th/plugins/vault) - การตั้งค่าผู้ให้บริการ HashiCorp Vault
- [ตัวแปรสภาพแวดล้อม](/th/help/environment) - ลำดับความสำคัญของสภาพแวดล้อม
- [พื้นผิวข้อมูลประจำตัว SecretRef](/th/reference/secretref-credential-surface) - พื้นผิวข้อมูลประจำตัว
- [สัญญาแผนการนำข้อมูลลับไปใช้](/th/gateway/secrets-plan-contract) - รายละเอียดสัญญาแผน
- [ความปลอดภัย](/th/gateway/security) - แนวทางด้านความปลอดภัย