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

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 หรือ _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

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

ตัวแปรสภาพแวดล้อมของส่วนติดต่อผู้ใช้

• 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_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
• ภาพรวมของโมเดล