oneai.agent_os.v1handoff schemaexecutor compatibilityprotocol safety

Reference: Agent OS Protocol Versioning

Version policy, compatibility rules, executor certification checklist, and OneClaw/OpenClaw integration expectations.

Current protocol versions

OneAI treats Agent OS as a protocol surface. Executors should integrate against protocolVersion and schemaVersion, not only endpoint paths.

Version	Status	Scope
oneai.agent_os.v1	Current	Handoff contracts, executor protocol, approval policy, proof callbacks, result ledger, and context preview.
oneai.handoff.v1	Current	Stored handoff contract shape used by OneAI, OneClaw, OpenClaw, bots, external agents, and human operators.

Compatibility policy

The goal is to let OneClaw, OpenClaw, bots, and customer executors evolve without breaking existing handoff integrations.

Additive fields

New optional fields may be added without changing the protocol version.

Breaking changes

Required field removals, renamed statuses, changed callback semantics, or changed execution boundary require a new protocol version.

Executor tolerance

Executors should ignore unknown fields and rely on requiredFields plus protocolVersion.

Approval safety

Executors must not act when approvalPolicy.status is PENDING_APPROVAL or REJECTED.

Proof safety

Executors should send proof before or with result when proofPolicy.required is true.

Executor certification checklist

Read protocolVersion and schemaVersion before processing.
Store handoffId and executorRunId for every run.
Validate approvalPolicy before any external action.
Return proof artifacts through /v1/executions/{handoffId}/proof.
Return final status through /v1/executions/{handoffId}/result.
Never include secrets, private credentials, or raw customer tokens in proof/result callbacks.
Treat OneAI as planner/ledger/verifier, not as the external execution actor.

Example protocol fetch

Executors can inspect the live protocol before integrating or before a new deployment.

curl -s https://oneai-saas-api-production.up.railway.app/v1/executor-protocol \
  -H "x-api-key: YOUR_KEY" | jq

Executor example kit

A complete OneAI → OpenClaw/OneClaw style lifecycle: protocol discovery, handoff contract, approval, proof, and final result.

# 1) Inspect protocol
curl -s https://oneai-saas-api-production.up.railway.app/v1/executor-protocol \
  -H "x-api-key: YOUR_KEY" | jq

# 2) Create a stored handoff contract
curl -s https://oneai-saas-api-production.up.railway.app/v1/handoff/contracts \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "objective": "Prepare a production launch checklist",
    "targetExecutor": "openclaw",
    "executorProtocol": "openclaw.v1",
    "riskLevel": "medium",
    "approvalMode": "manual",
    "proofRequired": ["execution log", "result summary"]
  }' | jq

# 3) Approve before external execution
curl -s -X POST https://oneai-saas-api-production.up.railway.app/v1/executions/HANDOFF_ID/approval \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "status": "APPROVED",
    "approvedBy": "operator",
    "reason": "Approved for OpenClaw execution."
  }' | jq

# 4) Executor reports proof
curl -s -X POST https://oneai-saas-api-production.up.railway.app/v1/executions/HANDOFF_ID/proof \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "executorType": "openclaw",
    "executorRunId": "openclaw_run_001",
    "status": "RUNNING",
    "proof": {
      "summary": "OpenClaw started execution.",
      "artifacts": [{ "type": "log", "text": "Executor accepted handoff." }]
    }
  }' | jq

# 5) Executor reports final result
curl -s -X POST https://oneai-saas-api-production.up.railway.app/v1/executions/HANDOFF_ID/result \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "executorType": "openclaw",
    "executorRunId": "openclaw_run_001",
    "status": "SUCCEEDED",
    "result": {
      "summary": "Execution completed.",
      "output": "Launch checklist prepared."
    }
  }' | jq

Agent OS

Models