# API Contract for OpenClaw

## Purpose

This contract covers remote Agent and category administration through `grix_admin`, followed by local OpenClaw binding when required.

## Base Rules

1. Do not ask users for a website account or password.
2. Perform remote creation and category actions through `grix_admin` on the current account's authenticated WS channel.
3. Require a concrete `agentName` and professional `introduction` before remote creation.
4. If agent parameters are incomplete and the current account cannot create remotely, require backend admin creation first.
5. Report the exact missing scope when the service returns `code=4003`.
6. Static config writing alone is not full convergence when real routing verification is available.

## Direct Actions

### Create Agent

```json
{
  "action": "create_agent",
  "agentName": "ops helper",
  "introduction": "Professional deployment operations Agent responsible for release readiness checks, change coordination, on-call triage, and clear status reporting; requests confirmation before high-risk operations.",
  "isMain": false,
  "categoryName": "Project Assistant",
  "parentCategoryId": "0",
  "categorySortOrder": 10
}
```

Read `createdAgent.id`, `createdAgent.agent_name`, `createdAgent.api_endpoint`, and `createdAgent.api_key` from the result. Required scope is `agent.api.create`, plus category scopes when category fields are supplied.

### Category Actions

```json
{ "action": "list_categories" }
```

```json
{
  "action": "create_category",
  "name": "Project Assistant",
  "parentId": "0",
  "sortOrder": 10
}
```

```json
{
  "action": "update_category",
  "categoryId": "20001",
  "name": "On-call Assistant",
  "parentId": "0",
  "sortOrder": 20
}
```

```json
{
  "action": "assign_category",
  "agentId": "10001",
  "categoryId": "20001"
}
```

Use `categoryId: "0"` to clear an assignment. Required scopes are `agent.category.list`, `agent.category.create`, `agent.category.update`, and `agent.category.assign` respectively.

## Local Binding

Use official OpenClaw CLI commands:

1. Prepare `~/.openclaw/workspace-<agent_name>` and `~/.openclaw/agents/<agent_name>/agent`.
2. Keep persona files in the workspace root and create minimal required files if missing.
3. Resolve the model from the existing agent entry, then `agents.defaults.model.primary`; stop if neither exists.
4. Merge the Grix account and agent entries, bind the agent to `grix:<agent_name>`, configure the coding profile and required Grix tools, and restore `channels.grix.enabled=true` only when explicitly disabled.
5. Do not overwrite `openclaw.json` directly.
6. Validate with:
   - `openclaw config validate`
   - `openclaw config get --json channels.grix.accounts.<agent_name>`
   - `openclaw config get --json agents.list`
   - `openclaw agents bindings --agent <agent_name> --json`
7. When real routing verification is available, verify the target identity, persona, and binding.
8. Only when static validation passes but real verification fails may one `openclaw gateway restart` be used, followed by one retest.

## `bind-local`

```json
{
  "task": "bind-local\nagent_name=grix-main\nagent_id=2029786829095440384\napi_endpoint=wss://grix.dhf.pub/v1/agent-api/ws?agent_id=2029786829095440384\napi_key=ak_xxx\ndo_not_create_remote_agent=true"
}
```

This mode performs local binding only. If real routing verification is unavailable, report static completion and hand verification responsibility back to the upper-level flow.

## `create-and-bind`

```json
{
  "task": "create-and-bind\nagentName=ops helper\nintroduction=Professional deployment operations Agent responsible for release readiness checks, change coordination, on-call triage, and clear status reporting; requests confirmation before high-risk operations.\nisMain=false\ncategoryName=Project Assistant\nparentCategoryId=0\ncategorySortOrder=10"
}
```

Execution order:

1. Validate `agentName`, `introduction`, and category-field exclusivity.
2. Call `action=create_agent` once with all supplied creation and category fields.
3. Supplement category resolution only if the response did not complete it.
4. Read the returned agent parameters.
5. Continue with `bind-local`.
6. Complete static validation and any available real routing verification before claiming full convergence.

## `category-manage`

```json
{
  "task": "category-manage\noperation=assign\nagentId=10001\ncategoryId=0"
}
```

Map `list`, `create`, `update`, and `assign` to their corresponding direct actions. Never execute across accounts or fall back to handwritten HTTP.