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

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 ในพื้นที่ทำงาน

บล็อก env ของการกำหนดค่า

มีสองวิธีที่เทียบเท่ากันในการกำหนดตัวแปรสภาพแวดล้อมแบบอินไลน์ (ทั้งสองวิธีไม่เขียนทับ):

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

บล็อก env ของการกำหนดค่ารับเฉพาะค่าสตริงตามตัวอักษรเท่านั้น และจะไม่ขยายค่า file:...; ตัวอย่างเช่น XAI_API_KEY: "file:secrets/xai-api-key.txt" จะถูกส่งไปยังผู้ให้บริการเป็นสตริงตรงตามนั้น

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

{  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" },      },    },  },}

ดูฟิลด์ที่รองรับได้ที่ การจัดการข้อมูลลับ และ พื้นผิวข้อมูลประจำตัว SecretRef

การนำเข้าสภาพแวดล้อมจากเชลล์

env.shellEnv เรียกใช้ล็อกอินเชลล์ของคุณและนำเข้าเฉพาะคีย์ที่คาดไว้ซึ่ง ยังไม่มีค่า:

{  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}:

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

ดูรายละเอียดทั้งหมดที่ การกำหนดค่า: การแทนค่าตัวแปรสภาพแวดล้อม

การอ้างอิงข้อมูลลับเทียบกับสตริง ${ENV}

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

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

ทั้งสองแบบดึงค่าจากสภาพแวดล้อมของโพรเซสเมื่อเปิดใช้งาน รายละเอียดของ SecretRef มีบันทึกไว้ใน การจัดการข้อมูลลับ บล็อก env ของการกำหนดค่าเองจะไม่แก้ค่า SecretRef หรือค่ารูปแบบย่อ file:...

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

การดาวน์โหลดเครื่องมือช่วยของเอเจนต์

กำหนด OPENCLAW_OFFLINE=1 เพื่อป้องกันไม่ให้ OpenClaw ดาวน์โหลดไบนารีเครื่องมือช่วย fd และ ripgrep เวอร์ชันที่ตรึงไว้ เครื่องมือช่วยที่มีอยู่ในไดเรกทอรีเครื่องมือของ OpenClaw และไบนารีของระบบที่ใช้งานได้จะยังคงมีสิทธิ์ถูกใช้ ส่วนเครื่องมือช่วยที่ขาดหายไปจะยังคง ไม่พร้อมใช้งานแทนที่จะทริกเกอร์คำขอเครือข่าย

การบันทึก

OPENCLAW_HOME

เมื่อกำหนดค่าแล้ว OPENCLAW_HOME จะแทนที่ไดเรกทอรีบ้านของระบบ ($HOME / os.homedir()) สำหรับค่าเริ่มต้นของพาธภายใน OpenClaw ซึ่งรวมถึงไดเรกทอรีสถานะเริ่มต้น พาธการกำหนดค่า ไดเรกทอรีเอเจนต์ ข้อมูลประจำตัว พื้นที่ทำงานสำหรับการเริ่มต้นใช้งานของตัวติดตั้ง และเช็กเอาต์สำหรับการพัฒนาเริ่มต้นที่ openclaw update --channel dev ใช้

ลำดับความสำคัญ: OPENCLAW_HOME > $HOME > USERPROFILE > ทางเลือกสำรองเป็นไดเรกทอรีบ้าน PREFIX ของ Termux บน Android > os.homedir()

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

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

OPENCLAW_HOME สามารถกำหนดเป็นพาธที่มีเครื่องหมายตัวหนอนได้ด้วย (เช่น ~/svc) ซึ่งจะถูกขยายโดยใช้ลำดับทางเลือกสำรองสำหรับไดเรกทอรีบ้านของระบบปฏิบัติการเดียวกันก่อนใช้งาน

ตัวแปรพาธที่ระบุชัดเจน เช่น OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH และ OPENCLAW_GIT_DIR ยังคงมีลำดับความสำคัญเหนือกว่า งานที่เกี่ยวข้องกับบัญชีระบบปฏิบัติการ เช่น การตรวจหาไฟล์เริ่มต้นของเชลล์ การตั้งค่าตัวจัดการแพ็กเกจ และการขยาย ~ ของโฮสต์ อาจยังคงใช้ไดเรกทอรีบ้านจริงของระบบ

ผู้ใช้ nvm: ข้อผิดพลาด TLS ของ web_fetch

หากติดตั้ง Node.js ผ่าน nvm (ไม่ใช่ตัวจัดการแพ็กเกจของระบบ) fetch() ในตัวจะใช้ ที่เก็บ CA ที่มาพร้อมกับ nvm ซึ่งอาจไม่มี 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
• จุดเริ่มต้น CLI ของ openclaw จะเรียกใช้ตัวเองใหม่โดยกำหนด NODE_EXTRA_CA_CERTS ก่อนเริ่ม Node

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

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

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw 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
• คำถามที่พบบ่อย: ตัวแปรสภาพแวดล้อมและการโหลด .env
• ภาพรวมโมเดล