# API Contract

## Purpose

`grix-admin` is responsible for local binding and runtime convergence, and when the current agent has the corresponding scope, supports completing the following through `grix_admin` via WS:

1. Create new remote API agents
2. Query agent categories under the current account
3. Create categories
4. Modify categories
5. Assign or clear categories for specified agents

## Base Rules

1. Do not ask users to provide website account/password for this flow.
2. All remote creation and category actions must go through `grix_admin` via the current account's authenticated WS channel.
3. If `agent_name` / `agent_id` / `api_endpoint` / `api_key` are incomplete, and the current account cannot create remotely, stop first and require backend admin to complete them.
4. The current agent must first have the corresponding scope enabled on the frontend permissions page; without scope, WS will fail directly.
5. For `bind-local` / `create-and-bind`, "config written successfully" does not equal completion; if this invocation already has real routing verification conditions, real verification passing must also be counted as part of the success criteria; otherwise explicitly hand the subsequent verification responsibility back to the upper-level flow.

## Direct `grix_admin` Contract

### 1. Create Remote Agent

```json
{
  "action": "create_agent",
  "agentName": "ops helper",
  "introduction": "Handles deployment and on-call collaboration",
  "isMain": false,
  "categoryName": "Project Assistant",
  "parentCategoryId": "0",
  "categorySortOrder": 10
}
```

Key fields to read from the return:

1. `createdAgent.id`
2. `createdAgent.agent_name`
3. `createdAgent.api_endpoint`
4. `createdAgent.api_key`

Required scope:

1. `agent.api.create`
2. If `categoryName` is included, may additionally need `agent.category.list`, `agent.category.create`, `agent.category.assign`
3. If `categoryId` is included, additionally needs `agent.category.assign`

### 2. List Categories

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

Required scope:

1. `agent.category.list`

### 3. Create Category

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

Required scope:

1. `agent.category.create`

### 4. Update Category

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

Required scope:

1. `agent.category.update`

### 5. Assign or Clear Category

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

Clear category:

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

Required scope:

1. `agent.category.assign`

## Local Bind Steps

After remote agent parameters are complete, continue with local binding through the official OpenClaw CLI:

1. Prepare local directories:
   - `workspace=~/.openclaw/workspace-<agent_name>`
   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
   - Add minimal `IDENTITY.md`, `SOUL.md`, `AGENTS.md` when required persona files are missing
2. Resolve `model` in this order:
   - The existing `model` from that local agent's entry
   - `agents.defaults.model.primary`
   - If still unavailable, clearly report error and stop
3. Read current config and merge:
   - `channels.grix.accounts`
   - `agents.list`
   - `tools.profile`
   - `tools.alsoAllow`
   - `tools.sessions.visibility`
4. Write back using official CLI:
   - `channels.grix.accounts.<agent_name>`
   - `agents.list`
   - `openclaw agents bind --agent <agent_name> --bind grix:<agent_name>`
   - `tools.profile`
   - `tools.alsoAllow`
   - `tools.sessions.visibility`
   - If needed, restore `channels.grix.enabled=true`
5. After writing, perform static validation first:
   - `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`
6. If this invocation already has real verification conditions, must immediately perform a real routing verification; reuse the current install/acceptance context, do not invent additional probes. Reply falling to the main agent, default assistant, old persona, or old config are all considered failures.
7. Only when step 5 static validation passes and this invocation itself handles step 6 real verification but verification fails, is one `openclaw gateway restart` allowed; after restart, must redo the same round of real routing verification.
8. If this invocation cannot perform real verification, can only state "config has been written, runtime not yet tested, needs subsequent flow to continue verification"; do not write it as "already fully taken effect".

## `bind-local` Input Contract

```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 prioritizes local binding; if this invocation has real verification conditions, must also complete real routing verification before it counts as full convergence; otherwise only complete static binding and explicitly hand subsequent verification responsibility to the upper-level flow.

## `create-and-bind` Input Contract

When the main agent already has an available account and `agent.api.create` scope, can enter the creation flow through `grix_admin.task`:

```json
{
  "task": "create-and-bind\nagentName=ops helper\nintroduction=Handles deployment and on-call collaboration\nisMain=false\ncategoryName=Project Assistant\nparentCategoryId=0\ncategorySortOrder=10"
}
```

This mode requires steps in order:

1. First make one direct call with `action=create_agent`, passing optional `categoryId` / `categoryName` / `parentCategoryId` / `categorySortOrder` together
2. If the return already includes the category assignment result, continue directly
3. If the caller used a legacy path, or the return does not include the category assignment result, supplement with:
   - `categoryId` -> `action=assign_category`
   - `categoryName` -> `action=list_categories`
   - Not found -> `action=create_category`
   - After obtaining category ID -> `action=assign_category`
4. Finally follow the same local binding and runtime convergence flow as `bind-local`

Notes:

1. `categoryId` and `categoryName` cannot be provided simultaneously
2. When matching `categoryName`, must also consider `parentCategoryId`
3. If the remote return indicates missing `agent.api.create` or any `agent.category.*` scope, clearly state which specific scope is missing

## `category-manage` Input Contract

When only doing subsequent category management, enter through `grix_admin.task`:

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

Mapping:

1. `operation=list` -> `action=list_categories`
2. `operation=create` -> `action=create_category`
3. `operation=update` -> `action=update_category`
4. `operation=assign` -> `action=assign_category`

Notes:

1. For `operation=assign`, `categoryId=0` means clear the category
2. No step can be executed cross-account
3. Do not hand-write HTTP or fall back to legacy scripts