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

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

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

1. สภาพแวดล้อมของกระบวนการ (สิ่งที่กระบวนการ Gateway มีอยู่แล้วจากเชลล์/daemon แม่)
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 เป็นตัวสำรองเพื่อความเข้ากันได้หลัง .env ส่วนกลางด้วย หากทั้งสองไฟล์มีอยู่และค่าไม่ตรงกัน OpenClaw จะใช้ ~/.openclaw/.env ต่อไปและพิมพ์คำเตือน

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

# บล็อก env ในการกำหนดค่า

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

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

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

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

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

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

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

# ตัวแปรสภาพแวดล้อมที่ถูกฉีดในรันไทม์

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

• OPENCLAW_SHELL=exec: ตั้งค่าสำหรับคำสั่งที่เรียกผ่านเครื่องมือ exec
• OPENCLAW_SHELL=acp: ตั้งค่าสำหรับการสร้างกระบวนการแบ็กเอนด์รันไทม์ ACP (เช่น acpx)
• OPENCLAW_SHELL=acp-client: ตั้งค่าสำหรับ openclaw acp client เมื่อสร้างกระบวนการสะพาน ACP
• OPENCLAW_SHELL=tui-local: ตั้งค่าสำหรับคำสั่งเชลล์ ! ของ TUI ภายในเครื่อง

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

# ตัวแปรสภาพแวดล้อมของ 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 มีเอกสารใน การจัดการความลับ

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

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

# การบันทึก

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

# OPENCLAW_HOME

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

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

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

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

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

# ผู้ใช้ 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 จะ re-exec ตัวเองพร้อมตั้งค่า NODE_EXTRA_CA_CERTS ก่อนเริ่มต้น Node

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

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

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