Li-Day-Day
58c19856fd
* feat(runtime): improve Lite gateway scheduling and proxy stability - Expand the runtime gateway port range to match 100 instances per pod - Scale runtime deployments based on pending backlog - Serialize gateway creation per pod and handle starting/creating states - Clean up missing gateway bindings from runtime agent reports - Improve Lite gateway proxy token stripping and auth header injection - Update deployment manifests, docs, and related tests * fix(runtime): harden Hermes Lite gateway recovery - Add hashed gateway token aliases for short-term token compatibility - Fix /resume conversations failing when old sessions use mismatched gateway tokens - Recover ports only from stale error bindings without affecting active gateways * feat(runtime): enable bidirectional desktop clipboard and direct proxy - Enable WebTop/Selkies/Kasm clipboard by default with per-instance overrides - Document clipboard verification, configuration pitfalls, and IME troubleshooting - Enable direct desktop proxy in the K8s and K3s manifests --------- Co-authored-by: litiantian03 <litiantian03@ieisystem.com>
4.1 KiB
clawmanager-agent V2 Contract
Purpose
The agent runs inside each shared OpenClaw or Hermes runtime Pod. It manages gateway subprocesses, ports, cgroups, Linux users, workspace quota, health checks, skill/status reporting, and metrics.
Agent-To-Backend Reports
All report requests use header X-ClawManager-Agent-Token.
POST /api/v1/runtime-agent/register
Request body:
{
"runtime_type": "openclaw",
"namespace": "clawmanager-system",
"pod_name": "openclaw-runtime-6f77f8b8c7-abcde",
"pod_uid": "pod-uid",
"pod_ip": "10.42.0.31",
"node_name": "node-a",
"deployment_name": "openclaw-runtime",
"image_ref": "ghcr.io/yuan-lab-llm/clawmanager-openclaw-image/openclaw:latest",
"agent_endpoint": "http://10.42.0.31:19090",
"capacity": 100
}
POST /api/v1/runtime-agent/heartbeat
Request body:
{
"pod_name": "openclaw-runtime-6f77f8b8c7-abcde",
"runtime_type": "openclaw",
"state": "ready",
"used_slots": 37,
"draining": false
}
POST /api/v1/runtime-agent/metrics/report
Request body:
{
"pod_name": "openclaw-runtime-6f77f8b8c7-abcde",
"cpu_millis_used": 13600,
"memory_bytes_used": 42949672960,
"disk_bytes_used": 214748364800,
"network_rx_bytes": 9223372,
"network_tx_bytes": 19223372,
"gateways": [
{
"instance_id": 123,
"gateway_id": "gw-123-7",
"port": 20017,
"state": "running",
"last_health_at": "2026-06-01T10:00:00Z"
}
]
}
Backend-To-Agent Commands
All command requests use header X-ClawManager-Control-Token.
ClawManager treats redirects from agent command endpoints as errors. Agents should return direct 2xx, 4xx, or 5xx responses instead of 3xx redirects.
GET /v1/health
The agent reports whether it can accept control-plane commands.
Success status: HTTP 200.
Success response body:
{
"status": "ready"
}
ClawManager currently treats any HTTP 2xx response as success and does not require a response body for this endpoint. Any non-2xx status is treated as an error.
POST /v1/gateways
The agent creates a gateway subprocess and returns the bound port. If no port is free in the requested range, return HTTP 409.
Request body:
{
"instance_id": 123,
"user_id": 45,
"agent_type": "openclaw",
"workspace_path": "/workspaces/openclaw/user-45/instance-123",
"port_range": {
"start": 20000,
"end": 20299
},
"uid": 200123,
"gid": 200123,
"cpu_cores": 2,
"memory_mb": 4096,
"disk_quota_mb": 20480,
"generation": 7
}
Success status: HTTP 200 or HTTP 201.
Success response body:
{
"gateway_id": "gw-123-7",
"port": 20017,
"pid": 8842,
"status": "running"
}
DELETE /v1/gateways/{gateway_id}
The agent stops the gateway and releases cgroup, process, and port resources.
gateway_id is URL path-escaped by ClawManager. Agents must decode the path segment before lookup.
Success status: HTTP 200, HTTP 202, or HTTP 204. ClawManager does not require a response body.
POST /v1/drain
The agent marks the Pod as draining and rejects new gateway creation. Existing gateways continue until ClawManager migrates them.
Request body:
{
"draining": true
}
Success status: HTTP 200 or HTTP 202. ClawManager does not require a response body.
Backend-To-Agent Error Responses
For now, agents should return a plain text response body for command errors.
When no port is free for POST /v1/gateways, return:
HTTP/1.1 409 Conflict
Content-Type: text/plain
no free port
ClawManager maps this to runtime agent conflict: no free port.
For general failures, return an appropriate non-2xx status with a short plain text body:
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain
failed to start gateway process
ClawManager includes both the status code and response body in the returned error.
Isolation Requirements
Every gateway runs as UID/GID 200000 + instance_id. The agent rejects workspace paths outside /workspaces/{runtime}/user-{user_id}/instance-{instance_id} after resolving symlinks. CPU and memory limits are enforced with cgroups. Workspace quota is enforced before writes.