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

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

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

OmeniaClaw gateway --port 18789# debug/trace mirrored to stdioOmeniaClaw gateway --port 18789 --verbose# force-kill listener on selected port, then startOmeniaClaw gateway --force

OmeniaClaw gateway statusOmeniaClaw statusOmeniaClaw logs --follow

OmeniaClaw channels status --probe

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

• process ที่ทำงานตลอดเวลาหนึ่งตัวสำหรับการ routing, control plane และการเชื่อมต่อ channel
• พอร์ตเดียวแบบ multiplexed สำหรับ:
  • WebSocket control/RPC
  • HTTP API ที่เข้ากันได้กับ OpenAI (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Control UI และ hooks
• โหมด bind เริ่มต้น: loopback
• ต้องมีการยืนยันตัวตนโดยค่าเริ่มต้น การตั้งค่า shared-secret ใช้ gateway.auth.token / gateway.auth.password (หรือ OmeniaClaw_GATEWAY_TOKEN / OmeniaClaw_GATEWAY_PASSWORD) และการตั้งค่า reverse-proxy แบบไม่ใช่ loopback สามารถใช้ gateway.auth.mode: "trusted-proxy" ได้

endpoint ที่เข้ากันได้กับ OpenAI

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

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

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

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

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

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

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

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

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

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

โหมด Hot reload

ชุดคำสั่งของ operator

OmeniaClaw gateway statusOmeniaClaw gateway status --deep   # adds a system-level service scanOmeniaClaw gateway status --jsonOmeniaClaw gateway installOmeniaClaw gateway restartOmeniaClaw gateway stopOmeniaClaw secrets reloadOmeniaClaw logs --followOmeniaClaw doctor

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

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

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

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

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

OmeniaClaw gateway status --deepOmeniaClaw gateway probe

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

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

Checklist ต่อ instance:

• gateway.port ที่ไม่ซ้ำ
• OmeniaClaw_CONFIG_PATH ที่ไม่ซ้ำ
• OmeniaClaw_STATE_DIR ที่ไม่ซ้ำ
• agents.defaults.workspace ที่ไม่ซ้ำ

ตัวอย่าง:

OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/a.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-a OmeniaClaw gateway --port 19001OmeniaClaw_CONFIG_PATH=~/.OmeniaClaw/b.json OmeniaClaw_STATE_DIR=~/.OmeniaClaw-b OmeniaClaw gateway --port 19002

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

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

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

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

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

ดู: Remote Gateway, Authentication, Tailscale.

การกำกับดูแลและ lifecycle ของ service

ใช้การรันแบบ supervised เพื่อความน่าเชื่อถือใกล้เคียง production

OmeniaClaw gateway installOmeniaClaw gateway statusOmeniaClaw gateway restartOmeniaClaw gateway stop

OmeniaClaw gateway installsystemctl --user enable --now OmeniaClaw-gateway[-<profile>].serviceOmeniaClaw gateway status

sudo loginctl enable-linger <user>

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

OmeniaClaw gateway installOmeniaClaw gateway status --jsonOmeniaClaw gateway restartOmeniaClaw gateway stop

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

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

OmeniaClaw --dev setupOmeniaClaw --dev gateway --allow-unconfiguredOmeniaClaw --dev status

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

อ้างอิงย่อของ Protocol (มุมมอง operator)

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

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

1. ack accepted ทันที (status:"accepted")
2. response การเสร็จสิ้นขั้นสุดท้าย (status:"ok"|"error") พร้อม event agent ที่ stream อยู่ระหว่างนั้น

ดูเอกสาร protocol ฉบับเต็ม: Gateway Protocol.

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

Liveness

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

Readiness

OmeniaClaw gateway statusOmeniaClaw channels status --probeOmeniaClaw health

การกู้คืน gap

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

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

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

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

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

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

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

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

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