docs/docs/th/help/environment.md

read_when	summary	title	x-i18n
คุณต้องทราบว่ามีการโหลดตัวแปรสภาพแวดล้อมใดบ้าง และโหลดตามลำดับใด คุณกำลังดีบัก API keys ที่หายไปใน Gateway คุณกำลังจัดทำเอกสารการยืนยันตัวตนของผู้ให้บริการหรือสภาพแวดล้อมการ deploy	ตำแหน่งที่ OpenClaw โหลดตัวแปรสภาพแวดล้อมและลำดับความสำคัญ	ตัวแปรสภาพแวดล้อม	generated_at model provider source_hash source_path workflow 2026-04-23T05:36:53Z gpt-5.4 openai a80aea69ca2ffe19a4e93140f05dd81fd576955562ff9913135d38a685a0353c help/environment.md 15

ตัวแปรสภาพแวดล้อม

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

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

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

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

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

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

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

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

การนำเข้า env จาก Shell

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

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

ตัวแปรสภาพแวดล้อมที่เทียบเท่า:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

ตัวแปร env ที่ inject ตอน runtime

OpenClaw ยัง inject ตัวบ่งชี้บริบทลงใน child processes ที่ถูก spawn:

• OPENCLAW_SHELL=exec: ตั้งค่าสำหรับคำสั่งที่รันผ่านเครื่องมือ exec
• OPENCLAW_SHELL=acp: ตั้งค่าสำหรับการ spawn โปรเซสของ ACP runtime backend (เช่น acpx)
• OPENCLAW_SHELL=acp-client: ตั้งค่าสำหรับ openclaw acp client เมื่อมัน spawn โปรเซส ACP bridge
• OPENCLAW_SHELL=tui-local: ตั้งค่าสำหรับคำสั่ง shell ! ของ TUI แบบ local

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

ตัวแปร env ของ UI

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

การแทนค่าด้วย env var ในคอนฟิก

คุณสามารถอ้างอิง env vars โดยตรงในค่าสตริงของคอนฟิก โดยใช้รูปแบบ ${VAR_NAME}:

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

ดู Configuration: Env var substitution สำหรับรายละเอียดทั้งหมด

Secret refs เทียบกับสตริง ${ENV}

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

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

ทั้งสองแบบจะ resolve จาก process env ตอน activation ดูรายละเอียด SecretRef ได้ใน Secrets Management

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

ตัวแปร	วัตถุประสงค์
OPENCLAW_HOME	แทนที่ home directory ที่ใช้สำหรับการ resolve พาธภายในทั้งหมด (~/.openclaw/, agent dirs, sessions, credentials) มีประโยชน์เมื่อรัน OpenClaw เป็น service user โดยเฉพาะ
OPENCLAW_STATE_DIR	แทนที่ state directory (ค่าเริ่มต้น ~/.openclaw)
OPENCLAW_CONFIG_PATH	แทนที่พาธไฟล์คอนฟิก (ค่าเริ่มต้น ~/.openclaw/openclaw.json)

Logging

ตัวแปร	วัตถุประสงค์
OPENCLAW_LOG_LEVEL	แทนที่ระดับ log สำหรับทั้งไฟล์และคอนโซล (เช่น debug, trace) มีความสำคัญเหนือ logging.level และ logging.consoleLevel ในคอนฟิก ค่าที่ไม่ถูกต้องจะถูกละเลยพร้อมคำเตือน

OPENCLAW_HOME

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

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

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

<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 (ไม่ใช่ package manager ของระบบ) fetch() ที่มีมาในตัวจะใช้ CA store ที่มากับ nvm ซึ่งอาจไม่มี modern root CAs (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

วิธีแก้แบบ manual (สำหรับรุ่นเก่าหรือการเปิดผ่าน node ... โดยตรง):

export ตัวแปรนี้ก่อนเริ่ม OpenClaw:

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

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

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

• Gateway configuration
• FAQ: env vars and .env loading
• ภาพรวม Models