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

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

# การเริ่มต้นแบบโลคัลใน 5 นาที

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

openclaw gateway status
openclaw status
openclaw logs --follow

openclaw channels status --probe

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

• โปรเซสที่ทำงานตลอดเวลาหนึ่งตัวสำหรับการกำหนดเส้นทาง, control plane และการเชื่อมต่อช่องทาง
• พอร์ตแบบมัลติเพล็กซ์เดียวสำหรับ:
  • WebSocket control/RPC
  • HTTP APIs ที่เข้ากันได้กับ OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Control UI และ hooks
• โหมด bind เริ่มต้น: loopback
• โดยค่าเริ่มต้นต้องมี auth การตั้งค่าแบบ shared-secret ใช้ gateway.auth.token / gateway.auth.password (หรือ OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) และการตั้งค่า reverse-proxy ที่ไม่ใช่ local 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 ส่วนใหญ่จะ probe /v1/models ก่อน
• ไปป์ไลน์ RAG และหน่วยความจำจำนวนมากคาดหวัง /v1/embeddings
• ไคลเอนต์แบบ agent-native นิยมใช้ /v1/responses มากขึ้น

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

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

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

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

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

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

# โหมด hot reload

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

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

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

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

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

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

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

openclaw gateway status --deep
openclaw gateway probe

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

• gateway status --deep อาจรายงาน Other gateway-like services detected (best effort) และพิมพ์คำแนะนำการล้างข้อมูลเมื่อยังมีการติดตั้ง launchd/systemd/schtasks เก่าค้างอยู่
• gateway probe อาจเตือนเกี่ยวกับ multiple reachable gateways เมื่อมีเป้าหมายมากกว่าหนึ่งรายการ ตอบกลับ
• หากเป็นความตั้งใจ ให้แยกพอร์ต, config/state และราก workspace ต่อ 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 19001
OPENCLAW_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

# การกำกับดูแลและวงจรชีวิตบริการ

ใช้การรันภายใต้การกำกับดูแลเพื่อความน่าเชื่อถือระดับใกล้เคียงโปรดักชัน

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

# เส้นทางด่วนสำหรับ dev profile

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

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

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

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

การรัน agent มีสองขั้น:

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

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

# การตรวจสอบเชิงปฏิบัติการ

# Liveness

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

# Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

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

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

# ลายเซ็นความล้มเหลวที่พบบ่อย

สำหรับลำดับการวินิจฉัยฉบับเต็ม ใช้ Gateway Troubleshooting

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

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

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

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

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

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