---
read_when:
    - คุณต้องรู้ว่าตัวแปรสภาพแวดล้อมใดถูกโหลด และโหลดตามลำดับใด
    - คุณกำลังดีบักคีย์ API ที่หายไปใน Gateway
    - คุณกำลังจัดทำเอกสารเกี่ยวกับการตรวจสอบสิทธิ์ของผู้ให้บริการหรือสภาพแวดล้อมการปรับใช้
summary: ตำแหน่งที่ OpenClaw โหลดตัวแปรสภาพแวดล้อมและลำดับความสำคัญ
title: ตัวแปรสภาพแวดล้อม
x-i18n:
    generated_at: "2026-05-11T20:31:41Z"
    model: gpt-5.5
    provider: openai
    source_hash: b4b91e9bb3c386292f11a3ffe5ae718a74a800bd19fe95073da990d881e6069d
    source_path: help/environment.md
    workflow: 16
---

OpenClaw ดึงตัวแปรสภาพแวดล้อมจากหลายแหล่ง กฎคือ **ห้ามเขียนทับค่าที่มีอยู่แล้วเด็ดขาด**

## ลำดับความสำคัญ (สูงสุด → ต่ำสุด)

1. **สภาพแวดล้อมของโปรเซส** (สิ่งที่โปรเซส Gateway มีอยู่แล้วจากเชลล์/ดีมอนแม่)
2. **`.env` ในไดเรกทอรีทำงานปัจจุบัน** (ค่าเริ่มต้นของ dotenv; ไม่เขียนทับ)
3. **`.env` ส่วนกลาง** ที่ `~/.openclaw/.env` (หรือ `$OPENCLAW_STATE_DIR/.env`; ไม่เขียนทับ)
4. **บล็อก `env` ในคอนฟิก** ใน `~/.openclaw/openclaw.json` (ใช้เฉพาะเมื่อค่านั้นหายไป)
5. **การนำเข้าจาก login shell แบบเลือกได้** (`env.shellEnv.enabled` หรือ `OPENCLAW_LOAD_SHELL_ENV=1`) ใช้เฉพาะกับคีย์ที่คาดไว้แต่ยังหายไป

บนการติดตั้งใหม่ของ Ubuntu ที่ใช้ไดเรกทอรีสถานะค่าเริ่มต้น OpenClaw ยังถือว่า `~/.config/openclaw/gateway.env` เป็น fallback เพื่อความเข้ากันได้หลัง `.env` ส่วนกลางด้วย หากทั้งสองไฟล์มีอยู่และค่าไม่ตรงกัน OpenClaw จะคง `~/.openclaw/.env` ไว้และพิมพ์คำเตือน

หากไฟล์คอนฟิกหายไปทั้งหมด ขั้นตอนที่ 4 จะถูกข้าม; การนำเข้าจากเชลล์ยังคงทำงานหากเปิดใช้งานไว้

## บล็อก `env` ในคอนฟิก

มีสองวิธีที่เทียบเท่ากันในการตั้งค่าตัวแปร env แบบอินไลน์ (ทั้งคู่ไม่เขียนทับ):

```json5
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}
```

## การนำเข้า env จากเชลล์

`env.shellEnv` จะรัน login shell ของคุณและนำเข้าเฉพาะคีย์ที่คาดไว้แต่ยัง **หายไป**:

```json5
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
```

ค่าตัวแปร env ที่เทียบเท่า:

- `OPENCLAW_LOAD_SHELL_ENV=1`
- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`

## ตัวแปร env ที่แทรกตอนรันไทม์

OpenClaw ยังแทรกตัวทำเครื่องหมายบริบทลงในโปรเซสลูกที่ถูกสร้างขึ้น:

- `OPENCLAW_SHELL=exec`: ตั้งค่าสำหรับคำสั่งที่รันผ่านเครื่องมือ `exec`
- `OPENCLAW_SHELL=acp`: ตั้งค่าสำหรับการสร้างโปรเซสแบ็กเอนด์รันไทม์ ACP (เช่น `acpx`)
- `OPENCLAW_SHELL=acp-client`: ตั้งค่าสำหรับ `openclaw acp client` เมื่อสร้างโปรเซสบริดจ์ ACP
- `OPENCLAW_SHELL=tui-local`: ตั้งค่าสำหรับคำสั่งเชลล์ `!` ของ TUI แบบโลคัล

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

## ตัวแปร env สำหรับ UI

- `OPENCLAW_THEME=light`: บังคับใช้พาเลต TUI แบบสว่างเมื่อเทอร์มินัลของคุณมีพื้นหลังสว่าง
- `OPENCLAW_THEME=dark`: บังคับใช้พาเลต TUI แบบมืด
- `COLORFGBG`: หากเทอร์มินัลของคุณส่งออกค่านี้ OpenClaw จะใช้คำใบ้สีพื้นหลังเพื่อเลือกพาเลต TUI อัตโนมัติ

## การแทนค่าตัวแปร env ในคอนฟิก

คุณสามารถอ้างอิงตัวแปร env โดยตรงในค่าสตริงของคอนฟิกได้โดยใช้ไวยากรณ์ `${VAR_NAME}`:

```json5
{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}
```

ดูรายละเอียดทั้งหมดได้ที่ [คอนฟิก: การแทนค่าตัวแปร env](/th/gateway/configuration-reference#env-var-substitution)

## การอ้างอิงความลับกับสตริง `${ENV}`

OpenClaw รองรับสองรูปแบบที่ขับเคลื่อนด้วย env:

- การแทนค่าสตริง `${VAR}` ในค่าคอนฟิก
- อ็อบเจกต์ SecretRef (`{ source: "env", provider: "default", id: "VAR" }`) สำหรับฟิลด์ที่รองรับการอ้างอิงความลับ

ทั้งสองแบบ resolve จาก env ของโปรเซสเมื่อเปิดใช้งาน รายละเอียดของ SecretRef มีบันทึกไว้ใน [การจัดการความลับ](/th/gateway/secrets)

## ตัวแปร env ที่เกี่ยวข้องกับพาธ

| ตัวแปร                  | วัตถุประสงค์                                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_HOME`          | เขียนทับไดเรกทอรี home ที่ใช้สำหรับการ resolve พาธภายในทั้งหมด (`~/.openclaw/`, ไดเรกทอรีเอเจนต์, เซสชัน, ข้อมูลรับรอง) มีประโยชน์เมื่อรัน OpenClaw เป็นผู้ใช้บริการเฉพาะ |
| `OPENCLAW_STATE_DIR`     | เขียนทับไดเรกทอรีสถานะ (ค่าเริ่มต้น `~/.openclaw`)                                                                                                                            |
| `OPENCLAW_CONFIG_PATH`   | เขียนทับพาธไฟล์คอนฟิก (ค่าเริ่มต้น `~/.openclaw/openclaw.json`)                                                                                                             |
| `OPENCLAW_INCLUDE_ROOTS` | รายการพาธของไดเรกทอรีที่คำสั่ง `$include` สามารถ resolve ไฟล์นอกไดเรกทอรีคอนฟิกได้ (ค่าเริ่มต้น: ไม่มี — `$include` ถูกจำกัดไว้ในไดเรกทอรีคอนฟิก) ขยาย tilde แล้ว  |

## การบันทึกล็อก

| ตัวแปร                          | วัตถุประสงค์                                                                                                                                                                                      |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_LOG_LEVEL`             | เขียนทับระดับล็อกสำหรับทั้งไฟล์และคอนโซล (เช่น `debug`, `trace`) มีความสำคัญเหนือ `logging.level` และ `logging.consoleLevel` ในคอนฟิก ค่าที่ไม่ถูกต้องจะถูกละเว้นพร้อมคำเตือน |
| `OPENCLAW_DEBUG_MODEL_TRANSPORT` | ส่งออกการวินิจฉัยเวลา request/response ของโมเดลแบบเจาะจงที่ระดับ `info` โดยไม่ต้องเปิดใช้งานล็อก debug ทั่วทั้งระบบ                                                                                  |
| `OPENCLAW_DEBUG_MODEL_PAYLOAD`   | การวินิจฉัย payload ของโมเดล: `summary`, `tools` หรือ `full-redacted` ค่า `full-redacted` ถูกจำกัดขนาดและปกปิดข้อมูลแล้ว แต่อาจมีข้อความ prompt/message รวมอยู่ด้วย                                               |
| `OPENCLAW_DEBUG_SSE`             | การวินิจฉัยสตรีมมิง: `events` สำหรับเวลาตั้งแต่เริ่มถึงเสร็จสิ้น, `peek` เพื่อรวมเหตุการณ์ SSE ห้ารายการแรกที่ปกปิดข้อมูลแล้ว                                                                                 |
| `OPENCLAW_DEBUG_CODE_MODE`       | การวินิจฉัยพื้นผิวโมเดลของโหมดโค้ด รวมถึงการซ่อนเครื่องมือของ provider และการบังคับใช้เฉพาะ exec/wait                                                                                          |

### `OPENCLAW_HOME`

เมื่อตั้งค่าแล้ว `OPENCLAW_HOME` จะแทนที่ไดเรกทอรี home ของระบบ (`$HOME` / `os.homedir()`) สำหรับการ resolve พาธภายในทั้งหมด ซึ่งทำให้บัญชีบริการแบบ headless แยกระบบไฟล์ได้เต็มรูปแบบ

**ลำดับความสำคัญ:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()`

**ตัวอย่าง** (macOS LaunchDaemon):

```xml
<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/user</string>
</dict>
```

`OPENCLAW_HOME` ยังสามารถตั้งเป็นพาธ tilde ได้ (เช่น `~/svc`) ซึ่งจะถูกขยายโดยใช้ `$HOME` ก่อนใช้งาน

## ผู้ใช้ nvm: ความล้มเหลว TLS ของ web_fetch

หากติดตั้ง Node.js ผ่าน **nvm** (ไม่ใช่ตัวจัดการแพ็กเกจของระบบ) `fetch()` ในตัวจะใช้
ที่เก็บ CA ที่มาพร้อมกับ nvm ซึ่งอาจไม่มี root CA รุ่นใหม่ (ISRG Root X1/X2 สำหรับ Let's Encrypt,
DigiCert Global Root G2 และอื่น ๆ) ทำให้ `web_fetch` ล้มเหลวด้วย `"fetch failed"` บนเว็บไซต์ HTTPS ส่วนใหญ่

บน Linux OpenClaw จะตรวจจับ nvm โดยอัตโนมัติและใช้การแก้ไขในสภาพแวดล้อมเริ่มต้นจริง:

- `openclaw gateway install` เขียน `NODE_EXTRA_CA_CERTS` ลงในสภาพแวดล้อมของบริการ systemd
- entrypoint ของ CLI `openclaw` จะ re-exec ตัวเองพร้อมตั้งค่า `NODE_EXTRA_CA_CERTS` ก่อนเริ่ม Node

**การแก้ไขด้วยตนเอง (สำหรับเวอร์ชันเก่าหรือการเปิดด้วย `node ...` โดยตรง):**

ส่งออกตัวแปรก่อนเริ่ม OpenClaw:

```bash
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
openclaw gateway run
```

อย่าพึ่งพาการเขียนตัวแปรนี้ลงใน `~/.openclaw/.env` เพียงอย่างเดียว; Node อ่าน
`NODE_EXTRA_CA_CERTS` ตอนเริ่มต้นโปรเซส

## ตัวแปรสภาพแวดล้อมรุ่นเก่า

OpenClaw อ่านเฉพาะตัวแปรสภาพแวดล้อม `OPENCLAW_*` เท่านั้น คำนำหน้าเดิม
`CLAWDBOT_*` และ `MOLTBOT_*` จากรุ่นก่อนหน้าจะถูกละเว้นอย่างเงียบ ๆ

หากค่ายังถูกตั้งอยู่ในโปรเซส Gateway ตอนเริ่มต้น OpenClaw จะส่งออก
คำเตือนการเลิกใช้ Node หนึ่งรายการ (`OPENCLAW_LEGACY_ENV_VARS`) ที่แสดง
คำนำหน้าที่ตรวจพบและจำนวนรวม เปลี่ยนชื่อแต่ละค่าโดยแทนที่
คำนำหน้าเดิมด้วย `OPENCLAW_` (เช่น `CLAWDBOT_GATEWAY_TOKEN` →
`OPENCLAW_GATEWAY_TOKEN`); ชื่อเก่าไม่มีผลใด ๆ

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

- [คอนฟิก Gateway](/th/gateway/configuration)
- [FAQ: ตัวแปร env และการโหลด .env](/th/help/faq#env-vars-and-env-loading)
- [ภาพรวมโมเดล](/th/concepts/models)