---
read_when:
- คุณจำเป็นต้องทราบว่ามีการโหลดตัวแปรสภาพแวดล้อมใดบ้างและโหลดตามลำดับใด
- คุณกำลังแก้ไขข้อบกพร่องเกี่ยวกับคีย์ API ที่หายไปใน Gateway
- คุณกำลังจัดทำเอกสารเกี่ยวกับการยืนยันตัวตนของผู้ให้บริการหรือสภาพแวดล้อมการปรับใช้
summary: ตำแหน่งที่ OpenClaw โหลดตัวแปรสภาพแวดล้อมและลำดับความสำคัญ
title: ตัวแปรสภาพแวดล้อม
x-i18n:
generated_at: "2026-07-19T07:14:48Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 32
provider: openai
source_hash: 9f9fdd67ee148931af2e15a12917871a0b85f80f763f0df3a978b7fd39b93eff
source_path: help/environment.md
workflow: 16
---
OpenClaw ดึงตัวแปรสภาพแวดล้อมจากหลายแหล่ง โดยมีกฎคือ **ห้ามเขียนทับค่าที่มีอยู่เดิม**
ไฟล์ `.env` ในพื้นที่ทำงานเป็นแหล่งที่มีระดับความน่าเชื่อถือต่ำกว่า: OpenClaw จะละเว้นข้อมูลประจำตัวของผู้ให้บริการและการควบคุมรันไทม์ที่ได้รับการปกป้องจาก `.env` ในพื้นที่ทำงานก่อนใช้ลำดับความสำคัญ
## ลำดับความสำคัญ (สูงสุดไปต่ำสุด)
1. **สภาพแวดล้อมของโพรเซส** (ค่าที่โพรเซส Gateway มีอยู่แล้วจากเชลล์/ดีมอนแม่)
2. **`.env` ในไดเรกทอรีทำงานปัจจุบัน** (ค่าเริ่มต้นของ dotenv; ไม่เขียนทับ; ข้อมูลประจำตัวของผู้ให้บริการและการควบคุมรันไทม์ที่ได้รับการปกป้องจะถูกละเว้น)
3. **`.env` ส่วนกลาง** ที่ `~/.openclaw/.env` (หรือที่เรียกว่า `$OPENCLAW_STATE_DIR/.env`; แนะนำสำหรับคีย์ API ของผู้ให้บริการ; ไม่เขียนทับ)
4. **บล็อก `env` ของการกำหนดค่า** ใน `~/.openclaw/openclaw.json` (ใช้เฉพาะเมื่อยังไม่มีค่า)
5. **การนำเข้าจากล็อกอินเชลล์แบบไม่บังคับ** (`env.shellEnv.enabled` หรือ `OPENCLAW_LOAD_SHELL_ENV=1`) ใช้เฉพาะกับคีย์ที่คาดไว้และยังไม่มีค่า
ในการติดตั้ง Ubuntu ใหม่ที่ใช้ไดเรกทอรีสถานะเริ่มต้น OpenClaw จะถือว่า `~/.config/openclaw/gateway.env` เป็นทางเลือกสำรองเพื่อความเข้ากันได้หลังจาก `.env` ส่วนกลางด้วย หากมีทั้งสองไฟล์และค่าไม่ตรงกัน OpenClaw จะคงค่า `~/.openclaw/.env` ไว้และแสดงคำเตือน
หากไม่มีไฟล์กำหนดค่าเลย จะข้ามขั้นตอนที่ 4 แต่การนำเข้าจากเชลล์จะยังทำงานหากเปิดใช้งานไว้
## ข้อมูลประจำตัวของผู้ให้บริการและ `.env` ในพื้นที่ทำงาน
อย่าเก็บคีย์ API ของผู้ให้บริการไว้เฉพาะใน `.env` ของพื้นที่ทำงาน OpenClaw บล็อกคีย์ข้อมูลประจำตัวและคีย์เปลี่ยนเส้นทางปลายทางของผู้ให้บริการจำนวนมากจากไฟล์ `.env` ในพื้นที่ทำงาน ซึ่งรวมถึงตัวแปรสภาพแวดล้อมสำหรับการยืนยันตัวตนของผู้ให้บริการที่รู้จักทั้งหมด (เช่น `GEMINI_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `GROQ_API_KEY`, `DEEPSEEK_API_KEY`, `PERPLEXITY_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY`, `FIRECRAWL_API_KEY`) รวมทั้งคีย์ใดก็ตามที่ลงท้ายด้วย `_API_HOST`, `_BASE_URL`, `_ENDPOINT` หรือ `_HOMESERVER` และเนมสเปซ `OPENCLAW_*`, `CLAWHUB_*`, `ANTHROPIC_API_KEY_*` และ `OPENAI_API_KEY_*` ทั้งหมด
ให้ใช้หนึ่งในแหล่งที่เชื่อถือได้ต่อไปนี้สำหรับข้อมูลประจำตัวของผู้ให้บริการแทน:
- สภาพแวดล้อมของโพรเซส Gateway เช่น เชลล์ หน่วย launchd/systemd ข้อมูลลับของคอนเทนเนอร์ หรือข้อมูลลับของ CI
- ไฟล์ dotenv ของรันไทม์ส่วนกลางที่ `~/.openclaw/.env` หรือ `$OPENCLAW_STATE_DIR/.env`
- บล็อก `env` ของการกำหนดค่าใน `~/.openclaw/openclaw.json`
- การนำเข้าจากล็อกอินเชลล์แบบไม่บังคับ เมื่อเปิดใช้งาน `env.shellEnv.enabled` หรือ `OPENCLAW_LOAD_SHELL_ENV=1`
หากก่อนหน้านี้เก็บคีย์ของผู้ให้บริการหรือค่าการกำหนดเส้นทางปลายทางไว้เฉพาะใน `.env` ของพื้นที่ทำงาน ให้ย้ายค่าเหล่านั้นไปยังแหล่งที่เชื่อถือได้แหล่งใดแหล่งหนึ่งข้างต้น `.env` ของพื้นที่ทำงานยังคงใช้กำหนดตัวแปรทั่วไปของโปรเจกต์ที่ไม่ใช่ข้อมูลประจำตัว การเปลี่ยนเส้นทางปลายทาง การเขียนทับโฮสต์ หรือการควบคุมรันไทม์ `OPENCLAW_*` ได้
ดูเหตุผลด้านความปลอดภัยที่ [ไฟล์ `.env` ในพื้นที่ทำงาน](/th/gateway/security#workspace-env-files)
## บล็อก `env` ของการกำหนดค่า
มีสองวิธีที่เทียบเท่ากันในการกำหนดตัวแปรสภาพแวดล้อมแบบอินไลน์ (ทั้งสองวิธีไม่เขียนทับ):
```json5
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: {
GROQ_API_KEY: "gsk-...",
},
},
}
```
บล็อก `env` ของการกำหนดค่ารับเฉพาะค่าสตริงตามตัวอักษรเท่านั้น และจะไม่ขยายค่า
`file:...`; ตัวอย่างเช่น `XAI_API_KEY: "file:secrets/xai-api-key.txt"`
จะถูกส่งไปยังผู้ให้บริการเป็นสตริงตรงตามนั้น
สำหรับคีย์ของผู้ให้บริการที่จัดเก็บในไฟล์ ให้ใช้ 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" },
},
},
},
}
```
ดูฟิลด์ที่รองรับได้ที่ [การจัดการข้อมูลลับ](/th/gateway/secrets) และ
[พื้นผิวข้อมูลประจำตัว SecretRef](/th/reference/secretref-credential-surface)
## การนำเข้าสภาพแวดล้อมจากเชลล์
`env.shellEnv` เรียกใช้ล็อกอินเชลล์ของคุณและนำเข้าเฉพาะคีย์ที่คาดไว้ซึ่ง **ยังไม่มีค่า**:
```json5
{
env: {
shellEnv: {
enabled: true,
timeoutMs: 15000,
},
},
}
```
ตัวแปรสภาพแวดล้อมที่เทียบเท่ากัน:
- `OPENCLAW_LOAD_SHELL_ENV=1`
- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000` (ค่าเริ่มต้น `15000`)
## สแนปช็อตของเชลล์สำหรับ Exec
บนโฮสต์ Gateway ที่ไม่ใช่ Windows คำสั่ง `exec` ของ bash และ zsh จะใช้สแนปช็อตเมื่อเริ่มต้นเป็นค่าเริ่มต้น
กำหนด `OPENCLAW_EXEC_SHELL_SNAPSHOT=0` ในสภาพแวดล้อมของโพรเซส Gateway เพื่อปิดใช้งานเส้นทางนี้
ค่า `false`, `no` และ `off` จะปิดใช้งานเช่นกัน ค่า `exec.env` ต่อการเรียกไม่สามารถสลับ
การใช้สแนปช็อตหรือเปลี่ยนเส้นทางแคชสแนปช็อตได้
## ตัวแปรสภาพแวดล้อมที่รันไทม์แทรก
OpenClaw ยังแทรกตัวบ่งชี้บริบทลงในโพรเซสลูกที่สร้างขึ้น:
- `OPENCLAW_SHELL=exec`: กำหนดให้คำสั่งที่เรียกผ่านเครื่องมือ `exec`
- `OPENCLAW_SHELL=acp-client`: กำหนดให้ `openclaw acp client` เมื่อสร้างโพรเซสบริดจ์ ACP
- `OPENCLAW_SHELL=tui-local`: กำหนดให้คำสั่งเชลล์ `!` ของ TUI ภายในเครื่อง
- `OPENCLAW_CLI=1`: กำหนดให้โพรเซสลูกที่สร้างโดยจุดเริ่มต้นของ CLI
สิ่งเหล่านี้เป็นตัวบ่งชี้รันไทม์ (ไม่ใช่การกำหนดค่าของผู้ใช้ที่จำเป็น) สามารถใช้ในตรรกะของเชลล์/โปรไฟล์
เพื่อใช้กฎเฉพาะตามบริบทได้
## ตัวแปรสภาพแวดล้อมของ UI
- `OPENCLAW_THEME=light`: บังคับใช้ชุดสีสว่างของ TUI เมื่อเทอร์มินัลมีพื้นหลังสีสว่าง
- `OPENCLAW_THEME=dark`: บังคับใช้ชุดสีมืดของ TUI
- `COLORFGBG`: หากเทอร์มินัลส่งออกค่านี้ OpenClaw จะใช้คำใบ้สีพื้นหลังเพื่อเลือกชุดสีของ TUI โดยอัตโนมัติ
## การแทนค่าตัวแปรสภาพแวดล้อมในการกำหนดค่า
สามารถอ้างอิงตัวแปรสภาพแวดล้อมโดยตรงในค่าสตริงของการกำหนดค่าโดยใช้ไวยากรณ์ `${VAR_NAME}`:
```json5
{
models: {
providers: {
"vercel-gateway": {
apiKey: "${VERCEL_GATEWAY_API_KEY}",
},
},
},
}
```
ดูรายละเอียดทั้งหมดที่ [การกำหนดค่า: การแทนค่าตัวแปรสภาพแวดล้อม](/th/gateway/configuration-reference#env-var-substitution)
## การอ้างอิงข้อมูลลับเทียบกับสตริง `${ENV}`
OpenClaw รองรับรูปแบบที่ขับเคลื่อนด้วยสภาพแวดล้อมสองแบบ:
- การแทนค่าสตริง `${VAR}` ในค่าการกำหนดค่า
- ออบเจ็กต์ SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) สำหรับฟิลด์ที่รองรับการอ้างอิงข้อมูลลับ
ทั้งสองแบบดึงค่าจากสภาพแวดล้อมของโพรเซสเมื่อเปิดใช้งาน รายละเอียดของ SecretRef มีบันทึกไว้ใน [การจัดการข้อมูลลับ](/th/gateway/secrets)
บล็อก `env` ของการกำหนดค่าเองจะไม่แก้ค่า SecretRef หรือค่ารูปแบบย่อ `file:...`
## ตัวแปรสภาพแวดล้อมที่เกี่ยวข้องกับพาธ
| ตัวแปร | วัตถุประสงค์ |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_HOME` | เขียนทับไดเรกทอรีบ้านที่ใช้สำหรับค่าเริ่มต้นของพาธภายใน OpenClaw (`~/.openclaw/`, ไดเรกทอรีเอเจนต์, เซสชัน, ข้อมูลประจำตัว, การเริ่มต้นใช้งานของตัวติดตั้ง และเช็กเอาต์สำหรับการพัฒนาเริ่มต้น) มีประโยชน์เมื่อเรียกใช้ OpenClaw ด้วยผู้ใช้บริการเฉพาะ |
| `OPENCLAW_STATE_DIR` | เขียนทับไดเรกทอรีสถานะ (ค่าเริ่มต้น `~/.openclaw`) |
| `OPENCLAW_CONFIG_PATH` | เขียนทับพาธของไฟล์กำหนดค่า (ค่าเริ่มต้น `~/.openclaw/openclaw.json`) |
| `OPENCLAW_INCLUDE_ROOTS` | รายการพาธของไดเรกทอรีที่ไดเรกทิฟ `$include` สามารถใช้แก้พาธไฟล์ภายนอกไดเรกทอรีกำหนดค่าได้ (ค่าเริ่มต้น: ไม่มี - `$include` ถูกจำกัดไว้ภายในไดเรกทอรีกำหนดค่า) มีการขยายเครื่องหมายตัวหนอน |
## การดาวน์โหลดเครื่องมือช่วยของเอเจนต์
กำหนด `OPENCLAW_OFFLINE=1` เพื่อป้องกันไม่ให้ OpenClaw ดาวน์โหลดไบนารีเครื่องมือช่วย `fd`
และ `ripgrep` เวอร์ชันที่ตรึงไว้ เครื่องมือช่วยที่มีอยู่ในไดเรกทอรีเครื่องมือของ OpenClaw
และไบนารีของระบบที่ใช้งานได้จะยังคงมีสิทธิ์ถูกใช้ ส่วนเครื่องมือช่วยที่ขาดหายไปจะยังคง
ไม่พร้อมใช้งานแทนที่จะทริกเกอร์คำขอเครือข่าย
## การบันทึก
| ตัวแปร | วัตถุประสงค์ |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_LOG_LEVEL` | เขียนทับระดับบันทึกสำหรับทั้งไฟล์และคอนโซล (เช่น `debug`, `trace`) มีลำดับความสำคัญเหนือ `logging.level` และ `logging.consoleLevel` ในการกำหนดค่า ค่าที่ไม่ถูกต้องจะถูกละเว้นพร้อมคำเตือน |
| `OPENCLAW_DEBUG_MODEL_TRANSPORT` | ส่งออกข้อมูลวินิจฉัยเวลาในการร้องขอ/การตอบกลับของโมเดลแบบเจาะจงที่ระดับ `info` โดยไม่เปิดใช้บันทึกการแก้ไขข้อบกพร่องส่วนกลาง |
| `OPENCLAW_DEBUG_MODEL_PAYLOAD` | ข้อมูลวินิจฉัยเพย์โหลดของโมเดล: `summary`, `tools` หรือ `full-redacted` ค่า `full-redacted` ถูกจำกัดขนาดและปกปิดข้อมูลแล้ว แต่อาจมีข้อความพรอมต์/ข้อความสนทนา |
| `OPENCLAW_DEBUG_SSE` | ข้อมูลวินิจฉัยการสตรีม: `events` สำหรับเวลาของเหตุการณ์แรก/เสร็จสิ้น และ `peek` เพื่อรวมเหตุการณ์ SSE ห้ารายการแรกที่ปกปิดข้อมูลแล้ว |
| `OPENCLAW_DEBUG_CODE_MODE` | ข้อมูลวินิจฉัยพื้นผิวโมเดลในโหมดโค้ด รวมถึงการซ่อนเครื่องมือของผู้ให้บริการและการบังคับใช้การควบคุม/คำสั่งโดยตรงแบบกะทัดรัด |
### `OPENCLAW_HOME`
เมื่อกำหนดค่าแล้ว `OPENCLAW_HOME` จะแทนที่ไดเรกทอรีบ้านของระบบ (`$HOME` / `os.homedir()`) สำหรับค่าเริ่มต้นของพาธภายใน OpenClaw ซึ่งรวมถึงไดเรกทอรีสถานะเริ่มต้น พาธการกำหนดค่า ไดเรกทอรีเอเจนต์ ข้อมูลประจำตัว พื้นที่ทำงานสำหรับการเริ่มต้นใช้งานของตัวติดตั้ง และเช็กเอาต์สำหรับการพัฒนาเริ่มต้นที่ `openclaw update --channel dev` ใช้
**ลำดับความสำคัญ:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > ทางเลือกสำรองเป็นไดเรกทอรีบ้าน `PREFIX` ของ Termux บน Android > `os.homedir()`
**ตัวอย่าง** (macOS LaunchDaemon):
```xml