Diagnostics

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

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

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

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

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

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

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

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

ตัวแปร 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.crtopenclaw gateway run

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