ocana-agent-ops

Create and troubleshoot Ocana agents. Use when creating a new Ocana agent, refreshing/repairing management token auth, diagnosing `ocana_agent_create` failures, checking `gatewayReachable`, handling a

SKILL.md

GitHub

Ocana Agent Ops

Minimum Model

Any model that can follow exact steps and compare status fields.


Default Path

  1. Prefer first-class tools first: ocana_agent_create, ocana_agent_get, ocana_agent_update, ocana_agent_lifecycle, ocana_agent_safe_operation.
  2. Use raw API only when testing or proving a platform bug.
  3. After every action, verify with ocana_agent_get.

Create a New Agent

ocana_agent_create(agentName, basePrompt, llmProvider, llmModel)

Then poll:

ocana_agent_get(agentId)

Healthy target:

  • status = running
  • gatewayReachable = true

If instanceStatus.state = running but agent is still provisioning and gatewayReachable = false, treat it as a provisioning problem, not success.


Management Token Refresh

Use when:

  • ocana_agent_create returns Invalid or expired token
  • direct management API calls fail on auth
  • MANAGEMENT_API_TOKEN is missing or stale

Refresh with the local gateway token:

GATEWAY_TOKEN=$(cat /path/to/openclaw/openclaw.json | python3 -c \
 "import json,sys; print(json.load(sys.stdin)['gateway']['auth']['token'])")
AGENT_ID=$(grep "^AGENT_ID" /path/to/ocana/agent-config.env | cut -d'=' -f2)
CONTROL_PLANE_URL=$(grep "^CONTROL_PLANE_URL" /path/to/ocana/agent-config.env | cut -d'=' -f2)

curl -s -X POST "$CONTROL_PLANE_URL/api/agents/$AGENT_ID/management-token/refresh" \
 -H "Authorization: Bearer $GATEWAY_TOKEN" \
 -H "Content-Type: application/json"

Then verify:

grep MANAGEMENT_API_TOKEN /path/to/ocana/agent-config.env

Rules:

  • If the refresh returns success but the token is not written to agent-config.env, treat that as a platform config bug.
  • If refresh says refreshed recently, wait for cooldown.
  • A refreshed token may fix raw API auth without fixing first-class tool auth. Treat those as separate auth paths if behavior differs.

Raw API Lifecycle Flow

Use only to prove behavior when the first-class lifecycle tool is blocked or ambiguous.

Headers:

  • Authorization: Bearer <MANAGEMENT_API_TOKEN>
  • x-agent-id: <target-agent-id>
  • Content-Type: application/json

Flow:

  1. POST /api/v1/agents/{agentId}/stop
  2. GET /api/v1/agents/{agentId}
  3. POST /api/v1/agents/{agentId}/reprovision

Known failure pattern:

  • stop works
  • agent becomes stopped
  • reprovision returns 400 because the server allows only failed/provisioning/starting

If that happens, log it as a lifecycle gate bug. The agent cannot self-recover.


Provisioning Failure Triage

If a fresh agent is stuck with:

  • status = provisioning
  • gatewayReachable = false
  • instanceStatus.state = running

run:

ocana_agent_safe_operation(agentId, operation="diagnostics_snapshot")

High-signal findings:

  • 226/NAMESPACE
  • /usr/bin/openclaw: No such file or directory
  • gateway service restart loops

Interpretation:

  • missing /usr/bin/openclaw = bad image/provisioning pipeline
  • diagnostics rejected because agent is not running = management/gateway state inconsistency

If the same pattern reproduces on a second fresh agent, treat it as a systemic platform bug, not an isolated instance issue.


ocana_agent_create vs Raw API

  • ocana_agent_create is the preferred path.
  • POST /api/v1/agents may reject direct agent-side curl with CSRF token mismatch; do not rely on curl for creation unless you have confirmed a supported auth path.
  • If ocana_agent_create fails but raw lifecycle calls work, the create-tool auth path is broken separately.

Inter-Agent Handoff Test

To validate a newly created agent end-to-end:

  1. Create the agent.
  2. Wait for running + gatewayReachable=true.
  3. Only then attempt handoff or session-based communication.

Do not treat instance running alone as enough.


Escalate When

Escalate to the platform owner/admin when any of these occur:

  • new agents consistently stay provisioning
  • /usr/bin/openclaw is missing on the instance
  • reprovision is blocked from stopped
  • MANAGEMENT_API_TOKEN refresh succeeds but does not persist
  • ocana_agent_create keeps returning Invalid or expired token while raw token refresh works

Escalation payload should include:

  • agentId
  • current status
  • gatewayReachable
  • exact error text
  • whether the bug reproduced on a second fresh agent