Platform Integration

Connect your claw server to ibl.ai and manage it through the platform's APIs and applications.

Source: github.com/iblai/iblai-claw-setup

Once connected, your claw instance is accessible from all ibl.ai applications -- Mentor AI, Skills AI, and any custom integration using the REST API. You register the server, bind mentors, configure agent identities and skills, and push configuration -- all through the same API that powers the ibl.ai platform UI.

---

Integration Flow

1. Register instance        POST claw/instances/
2. Test connectivity        POST claw/instances//test-connectivity/
3. Add model providers      POST claw/model-providers/
4. Push providers           POST claw/instances//push-providers/
5. Bind mentor              POST claw/mentor-configs/
6. Configure agent          PATCH agent-configs//
7. Create skills            POST agent-skills/  +  POST agent-skill-resources/
8. Assign skills            POST mentor-skill-assignments/
9. Push config              POST claw/mentor-configs//push-config/

All API calls use base path /api/ai-mentor/orgs// and require authentication.

---

Part 1: Connect Your Server to ibl.ai

Register your instance

POST /api/ai-mentor/orgs//claw/instances/
Content-Type: application/json

{
  "name": "My OpenClaw Instance",
  "claw_type": "openclaw",
  "server_url": "https://your-domain.example.com",
  "gateway_token": "your-gateway-token-from-setup"
}

Device identity (required for OpenClaw): The platform needs an Ed25519 keypair for device identity signing. Without it, config push will fail with "missing scope: operator.read". Generate a keypair and include it in connection_params:

{
  "device_identity": {
    "private_key_pem": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n"
  }
}

See server setup step 5.2 for how to generate the keypair.

Save the id from the response -- you'll need it for subsequent steps.

Response (201 Created):

{
  "id": 1,
  "name": "My OpenClaw Instance",
  "claw_type": "openclaw",
  "provision_mode": "self_hosted",
  "server_url": "https://your-domain.example.com",
  "deployment_backend": null,
  "status": "active",
  "deploy_state": "ready",
  "platform_key": "your-org",
  "last_health_check": null,
  "last_health_status": null,
  "claw_version": null,
  "created_at": "2026-03-18T10:00:00Z",
  "updated_at": "2026-03-18T10:00:00Z"
}

Write-only fields (gateway_token, auth_headers, connection_params) are never returned in responses.

Test connectivity

POST /api/ai-mentor/orgs//claw/instances//test-connectivity/

Response (200 OK):

{
  "checks": [
    {"name": "tls_reachable", "passed": true, "detail": "200 OK"},
    {"name": "health_check", "passed": true, "detail": "healthy"}
  ],
  "all_passed": true
}

If tls_reachable fails: check your domain DNS and Caddy config. If health_check fails: check that the OpenClaw gateway is running (systemctl --user status openclaw-gateway).

Other instance operations

Instance status values: active, inactive, error Deploy state values: pending, deploying, ready, teardown, failed

---

Part 2: Configure and Call from ibl.ai

Once your server is registered, you manage everything through the ibl.ai API. This means all ibl.ai applications -- Mentor AI chat, Skills AI, custom integrations -- can use your claw instance. Configuration, agent identities, skills, and model providers are all pushed from the platform to your server.

Set up a model provider (optional)

If you want to use a different LLM provider (e.g. OpenRouter) instead of the default Anthropic:

POST /api/ai-mentor/orgs//claw/model-providers/
Content-Type: application/json

{
  "server": 1,
  "name": "openrouter",
  "base_url": "https://openrouter.ai/api/v1",
  "api_type": "openai-completions",
  "credential_name": "openrouter",
  "credential_key": "key",
  "model_catalog": [
    {"id": "anthropic/claude-sonnet-4-6", "name": "Claude Sonnet"},
    {"id": "meta-llama/llama-3.2-3b-instruct:free", "name": "Llama 3.2 (free)"}
  ],
  "enabled": true,
  "models_mode": "merge"
}

Then push providers to the instance:

POST /api/ai-mentor/orgs//claw/instances//push-providers/

Response (202 Accepted):

{"queued": true, "message": "Provider push queued."}

The credential_resolved field in provider responses indicates whether an LLMCredential with the given credential_name exists on the platform.

Bind a mentor to the instance

POST /api/ai-mentor/orgs//claw/mentor-configs/
Content-Type: application/json

{
  "mentor": "",
  "server": 1,
  "enabled": true
}

This automatically creates an AgentConfig for the mentor if one doesn't exist.

Response (201 Created):

{
  "id": 1,
  "mentor": "6f29a5eb-c657-4a76-8a19-4ea58175d008",
  "server": 1,
  "server_name": "My OpenClaw Instance",
  "agent_config": {},
  "enabled": true,
  "auto_push": false,
  "last_config_push": null,
  "last_config_push_status": null,
  "last_push_warnings": []
}

Configure the agent

Agent configuration defines the workspace files and settings that get pushed to the claw instance. Each text field maps to a markdown file in the agent's workspace:

PATCH /api/ai-mentor/orgs//agent-configs//
Content-Type: application/json

{
  "identity": "Name: Study Buddy\nVibe: Friendly and patient",
  "soul": "Always encourage the student. Be concise.",
  "model": "anthropic/claude-sonnet-4-6"
}

All text fields are optional and default to empty string. The config field defaults to {}.

Blocked config paths (rejected on write): gateway.auth, gateway.controlUi.dangerouslyDisableDeviceAuth, tools.exec.host, sandbox.mode, hooks.allowUnsafeExternalContent.

Push configuration to the instance

POST /api/ai-mentor/orgs//claw/mentor-configs//push-config/

Response (202 Accepted):

{"queued": true, "message": "Config push queued."}

A successful push sets workspace files (IDENTITY.md, SOUL.md, etc.) and applies config patches on the instance. The gateway restarts itself after a config patch.

Device pairing

The first time the platform pushes config, the instance may require device pairing approval. If the push fails with a pairing error:

1. SSH into your server
2. Run: openclaw devices list
3. Find the pending request and approve it: openclaw devices approve

This only needs to be done once per platform connection. See Device Re-Pairing if pairing is lost after updates.

---

Skills Management

Skills are reusable capabilities that can be assigned to mentors. When config is pushed, enabled skill assignments are sent to the instance.

Create a skill

POST /api/ai-mentor/orgs//agent-skills/
Content-Type: application/json

{
  "name": "Web Research",
  "slug": "web-research",
  "description": "Research topics using web search",
  "version": "1.0.0",
  "instruction": "## Instructions\n1. Search for the topic\n2. Summarize key findings\n3. Cite sources",
  "metadata": {
    "openclaw": {
      "requires": {"bins": ["curl"]}
    }
  },
  "enabled": true
}

Add resources to a skill

Skills can have attached files -- scripts, references, or binary assets:

For scripts and references (text content):

POST /api/ai-mentor/orgs//agent-skill-resources/
Content-Type: application/json

{
  "skill": 1,
  "file_type": "script",
  "filename": "fetch_data.py",
  "content": "import requests\n\ndef fetch(url):\n    return requests.get(url).text"
}

For assets (binary files): Use multipart form with a file field instead of content.

Assign skills to mentors

POST /api/ai-mentor/orgs//mentor-skill-assignments/
Content-Type: application/json

{
  "mentor": "",
  "skill": 1,
  "enabled": true
}

A mentor can only be assigned to the same skill once. Enabled assignments are pushed as skills.entries when you push config.

---

Complete Example

Here's a full walkthrough: register a server, bind a mentor, configure it, and push.

1. Register the instance

curl -X POST https://platform.ibl.ai/api/ai-mentor/orgs/my-org/claw/instances/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -d '{
    "name": "Production OpenClaw",
    "claw_type": "openclaw",
    "server_url": "https://claw.mycompany.com",
    "gateway_token": "abc123..."
  }'
# Save the returned "id" (e.g. 1)

2. Test connectivity

curl -X POST https://platform.ibl.ai/api/ai-mentor/orgs/my-org/claw/instances/1/test-connectivity/ \
  -H "Authorization: Token YOUR_API_TOKEN"
# Both checks should pass

3. Bind a mentor

curl -X POST https://platform.ibl.ai/api/ai-mentor/orgs/my-org/claw/mentor-configs/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -d '{
    "mentor": "6f29a5eb-c657-4a76-8a19-4ea58175d008",
    "server": 1,
    "enabled": true
  }'
# Save the returned "id" (e.g. 1)

4. Configure the agent

curl -X PATCH https://platform.ibl.ai/api/ai-mentor/orgs/my-org/agent-configs/1/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -d '{
    "identity": "Name: Study Buddy\nVibe: Friendly and patient tutor",
    "soul": "Always encourage the student. Never give answers directly. Be concise.",
    "model": "anthropic/claude-sonnet-4-6",
    "config": {
      "heartbeat": {"every": "30m"},
      "session": {"dmScope": "per-channel-peer"}
    }
  }'

5. Push config

curl -X POST https://platform.ibl.ai/api/ai-mentor/orgs/my-org/claw/mentor-configs/1/push-config/ \
  -H "Authorization: Token YOUR_API_TOKEN"
# Response: {"queued": true, "message": "Config push queued."}

6. Approve device pairing (first time only)

# SSH into your claw server
ssh root@claw.mycompany.com
openclaw devices list
openclaw devices approve 

7. Chat

Open the mentor in any ibl.ai application and send a message. Responses stream from your OpenClaw instance through the platform to the user.

---

API Reference Summary

All endpoints are tenant-scoped under /api/ai-mentor/orgs//. Responses are JSON. List endpoints support limit and offset pagination.

Claw Instances

Mentor Configs

Agent Configs

Agent Skills

Skill Resources

Mentor Skill Assignments

Model Providers