คู่มือปฏิบัติการ Gateway

ใช้หน้านี้สำหรับการเริ่มต้นวันแรกและการปฏิบัติการวันที่สองของบริการ Gateway

การเริ่มต้นในเครื่องภายใน 5 นาที

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

โมเดลรันไทม์

• กระบวนการที่เปิดตลอดหนึ่งกระบวนการสำหรับการกำหนดเส้นทาง, control plane และการเชื่อมต่อช่องทาง
• พอร์ตเดียวแบบ multiplex สำหรับ:
  • การควบคุม/RPC ผ่าน WebSocket
  • HTTP APIs (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • เส้นทาง HTTP ของ Plugin เช่น /api/v1/admin/rpc ที่เป็นตัวเลือก
  • Control UI และ hook
• โหมด bind เริ่มต้น: loopback
• ต้องมีการยืนยันตัวตนโดยค่าเริ่มต้น การตั้งค่าแบบ shared-secret ใช้ gateway.auth.token / gateway.auth.password (หรือ OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) และการตั้งค่า reverse-proxy แบบ non-loopback สามารถใช้ gateway.auth.mode: "trusted-proxy" ได้

เอนด์พอยต์ที่เข้ากันได้กับ OpenAI

พื้นผิวความเข้ากันได้ที่ให้ประโยชน์สูงสุดของ OpenClaw ตอนนี้คือ:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

เหตุผลที่ชุดนี้สำคัญ:

• การผสานรวม Open WebUI, LobeChat และ LibreChat ส่วนใหญ่มักตรวจสอบ /v1/models ก่อน
• pipeline ของ RAG และหน่วยความจำจำนวนมากคาดหวัง /v1/embeddings
• ไคลเอนต์แบบ agent-native นิยมใช้ /v1/responses มากขึ้น

หมายเหตุการวางแผน:

• /v1/models ให้ความสำคัญกับเอเจนต์ก่อน: ส่งคืน openclaw, openclaw/default และ openclaw/<agentId>
• openclaw/default เป็น alias ที่เสถียรซึ่งแมปไปยังเอเจนต์เริ่มต้นที่กำหนดค่าไว้เสมอ
• ใช้ x-openclaw-model เมื่อคุณต้องการ override provider/model ของ backend; มิฉะนั้น การตั้งค่าโมเดลและ embedding ปกติของเอเจนต์ที่เลือกจะยังคงควบคุมอยู่

ทั้งหมดนี้รันบนพอร์ต Gateway หลักและใช้ขอบเขตการยืนยันตัวตนของผู้ปฏิบัติการที่เชื่อถือได้เดียวกันกับส่วนที่เหลือของ Gateway HTTP API

Admin HTTP RPC (POST /api/v1/admin/rpc) เป็นเส้นทาง Plugin แยกต่างหากที่ปิดโดยค่าเริ่มต้น สำหรับเครื่องมือโฮสต์ที่ใช้ WebSocket RPC ไม่ได้ ดู Admin HTTP RPC

ลำดับความสำคัญของพอร์ตและ bind

บริการ Gateway ที่ติดตั้งแล้วจะบันทึก --port ที่แก้ค่าแล้วไว้ใน metadata ของ supervisor หลังจากเปลี่ยน gateway.port ให้รัน openclaw doctor --fix หรือ openclaw gateway install --force เพื่อให้ launchd/systemd/schtasks เริ่มกระบวนการบนพอร์ตใหม่

การเริ่มต้น Gateway ใช้พอร์ตและ bind ที่มีผลเดียวกันเมื่อ seed origin ของ Control UI ในเครื่องสำหรับ bind แบบ non-loopback ตัวอย่างเช่น --bind lan --port 3000 จะ seed http://localhost:3000 และ http://127.0.0.1:3000 ก่อนที่การตรวจสอบ รันไทม์จะรัน เพิ่ม origin ของเบราว์เซอร์ระยะไกล เช่น HTTPS proxy URLs ลงใน gateway.controlUi.allowedOrigins อย่างชัดเจน

โหมด hot reload

ชุดคำสั่งสำหรับผู้ปฏิบัติการ

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep ใช้สำหรับการค้นพบบริการเพิ่มเติม (LaunchDaemons/หน่วย systemd system /schtasks) ไม่ใช่การตรวจสอบสุขภาพ RPC ที่ลึกขึ้น

Gateway หลายตัว (โฮสต์เดียวกัน)

การติดตั้งส่วนใหญ่ควรรันหนึ่ง Gateway ต่อเครื่อง Gateway เดียวสามารถโฮสต์ เอเจนต์และช่องทางได้หลายรายการ

คุณต้องมี Gateway หลายตัวเฉพาะเมื่อคุณตั้งใจต้องการการแยกส่วนหรือบอทกู้คืน

การตรวจสอบที่มีประโยชน์:

openclaw gateway status --deepopenclaw gateway probe

สิ่งที่คาดหวัง:

• gateway status --deep อาจรายงาน Other gateway-like services detected (best effort) และพิมพ์คำแนะนำการล้างข้อมูลเมื่อยังมีการติดตั้ง launchd/systemd/schtasks เก่าค้างอยู่
• gateway probe อาจเตือนเกี่ยวกับ multiple reachable gateway identities เมื่อ Gateway ที่แตกต่างกันตอบกลับ หรือเมื่อ OpenClaw พิสูจน์ไม่ได้ว่าเป้าหมายที่เข้าถึงได้เป็น Gateway เดียวกัน SSH tunnel, proxy URL หรือ URL ระยะไกลที่กำหนดค่าไว้ไปยัง Gateway เดียวกันนับเป็น Gateway เดียวที่มีหลาย transport แม้พอร์ต transport จะแตกต่างกัน
• หากเป็นความตั้งใจ ให้แยกพอร์ต, config/state และ workspace root ต่อ Gateway

รายการตรวจสอบต่อ instance:

• gateway.port ที่ไม่ซ้ำกัน
• OPENCLAW_CONFIG_PATH ที่ไม่ซ้ำกัน
• OPENCLAW_STATE_DIR ที่ไม่ซ้ำกัน
• agents.defaults.workspace ที่ไม่ซ้ำกัน

ตัวอย่าง:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

การตั้งค่าโดยละเอียด: /gateway/multiple-gateways

การเข้าถึงระยะไกล

แนะนำ: Tailscale/VPN ทางเลือกสำรอง: SSH tunnel

ssh -N -L 18789:127.0.0.1:18789 user@host

จากนั้นเชื่อมต่อไคลเอนต์ภายในเครื่องไปที่ ws://127.0.0.1:18789

ดู: Remote Gateway, Authentication, Tailscale

การควบคุมดูแลและวงจรชีวิตบริการ

ใช้การรันแบบมี supervisor เพื่อความน่าเชื่อถือระดับใกล้ production

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

เส้นทางด่วนสำหรับโปรไฟล์ Dev

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

ค่าเริ่มต้นรวมถึง state/config ที่แยกไว้ และพอร์ต Gateway พื้นฐาน 19001

เอกสารอ้างอิงย่อของโปรโตคอล (มุมมองผู้ปฏิบัติการ)

• เฟรมแรกของไคลเอนต์ต้องเป็น connect
• Gateway ส่งคืนสแนปช็อต hello-ok (presence, health, stateVersion, uptimeMs, limits/policy)
• hello-ok.features.methods / events เป็นรายการค้นพบแบบอนุรักษ์นิยม ไม่ใช่ dump ที่สร้างจากทุกเส้นทาง helper ที่เรียกได้
• คำขอ: req(method, params) → res(ok/payload|error)
• เหตุการณ์ทั่วไปประกอบด้วย connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, เหตุการณ์วงจรชีวิตการจับคู่/การอนุมัติ และ shutdown

การรันเอเจนต์มีสองขั้นตอน:

1. ack ยอมรับทันที (status:"accepted")
2. การตอบกลับเมื่อเสร็จสิ้นสุดท้าย (status:"ok"|"error") พร้อมเหตุการณ์ agent แบบสตรีมระหว่างทาง

ดูเอกสารโปรโตคอลฉบับเต็ม: Gateway Protocol

การตรวจสอบการปฏิบัติการ

ความมีชีวิต

• เปิด WS และส่ง connect
• คาดหวังการตอบกลับ hello-ok พร้อมสแนปช็อต

ความพร้อม

openclaw gateway statusopenclaw channels status --probeopenclaw health

การกู้คืนช่องว่าง

เหตุการณ์จะไม่ถูก replay เมื่อมีช่องว่างของลำดับ ให้รีเฟรชสถานะ (health, system-presence) ก่อนดำเนินการต่อ

รูปแบบความล้มเหลวที่พบบ่อย

สำหรับลำดับขั้นการวินิจฉัยแบบครบถ้วน ให้ใช้ การแก้ไขปัญหา Gateway

การรับประกันด้านความปลอดภัย

• ไคลเอนต์โปรโตคอล Gateway ล้มเหลวอย่างรวดเร็วเมื่อ Gateway ไม่พร้อมใช้งาน (ไม่มี fallback ไปยัง direct-channel โดยนัย)
• เฟรมแรกที่ไม่ถูกต้องหรือไม่ใช่การเชื่อมต่อจะถูกปฏิเสธและปิด
• การปิดระบบอย่างนุ่มนวลจะปล่อยเหตุการณ์ shutdown ก่อนปิดซ็อกเก็ต

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

• การแก้ไขปัญหา
• กระบวนการเบื้องหลัง
• การกำหนดค่า
• สุขภาพ
• Doctor
• การยืนยันตัวตน

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

• การกำหนดค่า
• การแก้ไขปัญหา Gateway
• การเข้าถึงระยะไกล
• การจัดการความลับ