---
name: grix-admin
description: Grix agent administration for OpenClaw — create remote API agents, manage agent categories, and rotate API keys through `grix_admin`, and bind an agent's remote parameters into the local OpenClaw configuration with validation and routing verification. For "create me an agent for X" requests, run `grix-egg` discovery first; use this skill when the user already has agent parameters to bind, asks for category management, or grix-egg found no matching egg / the user wants a blank agent.
---

# Grix Agent Admin (OpenClaw)

Three workflows:

| Workflow | What it does |
|---|---|
| [`bind-local`](#workflow-a--bind-local) | Bind an existing remote agent's parameters into local OpenClaw, validate, verify routing |
| [`create-and-bind`](#workflow-b--create-and-bind) | Create a remote agent via `grix_admin`, then run `bind-local` |
| [`category-manage`](#workflow-c--category-manage) | List / create / update / assign categories via `grix_admin` |

## Two ways `grix_admin` is called

1. **Delegated workflow** — the caller passes only `task`, whose first line
   names the workflow (`bind-local`, `create-and-bind`, `category-manage`)
   followed by `key=value` lines. `grix-register` hands off this way. You then
   run the workflow described below.
2. **Direct action** — pass `action` plus its fields (table below). Use this
   for every remote call *inside* a workflow. `task` and `action` cannot be
   combined in one call.

**Creating a new agent from a business description?** Run the `grix-egg` skill
first (search the egg market, let the owner hatch a ready-made egg). Come here
for creation only when no egg matched or the user explicitly wants a blank
agent — and say so in your reply.

All remote operations go through `grix_admin` on the current account's WS
channel — never hand-written HTTP or scripts, never across accounts, and
never ask the user for a website account or password.

## `grix_admin` direct actions

| `action` | Required | Optional |
|---|---|---|
| `create_agent` | `agentName`, `introduction` | `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder` |
| `list_categories` | — | — |
| `create_category` | `name`, `parentId` | `sortOrder` |
| `update_category` | `categoryId`, `name`, `parentId` | `sortOrder` |
| `assign_category` | `agentId`, `categoryId` (`0` clears) | — |
| `rotate_api_key` | `agentId` | — |

Notes:

- `categoryId` and `categoryName` are mutually exclusive — report the conflict
  and stop if both are given.
- With `categoryName`, the backend looks for an exact match under
  `parentCategoryId`, creating it if absent. If several exact matches exist,
  stop and ask the owner for an explicit `categoryId`.
- `isMain=true` only when actually creating a new main API agent.
- `code=4003` means a missing scope — report the exact `agent.api.create` or
  `agent.category.*` scope.

## Agent creation intake (before any `create_agent`)

1. `agentName` and `introduction` must both be present and specific. Never
   create an agent with an empty, generic, or placeholder introduction.
2. If either is missing or vague, ask one concise question in the user's
   language: what does this agent mainly do — core responsibilities, whom it
   serves, and its boundaries?
3. Turn the answer into a concise professional `agentName` and an
   `introduction` that states purpose, core responsibilities, intended users or
   scenarios, operating expectations, and boundaries. Treat `introduction` as
   the agent's behavioral specification, not marketing copy.
4. Preserve the user's facts and intent; do not invent permissions, authority,
   or expertise they did not grant.

## Workflow A — `bind-local`

Inputs: `agent_name`, `agent_id`, `api_endpoint`, `api_key` (all required).
Missing field → say which and stop. Do not create anything remotely, and do
not call back to `grix-register`.

1. Prepare local directories: `workspace=~/.openclaw/workspace-<agent_name>`
   and `agentDir=~/.openclaw/agents/<agent_name>/agent`. Persona files live
   only in the workspace root; add minimal `IDENTITY.md`, `SOUL.md`, and
   `AGENTS.md` if missing.
2. Read the current account, agent, tool profile, tool allowlist, session
   visibility, and binding configuration.
3. Resolve `model`: reuse the existing agent model, else
   `agents.defaults.model.primary`; if neither exists, report the missing
   model and stop.
4. Merge the account and agent entries, bind the agent to
   `grix:<agent_name>`, set the coding tool profile and required Grix tools,
   and restore `channels.grix.enabled=true` only if it was explicitly
   disabled. Apply each change with the official OpenClaw CLI item by item —
   never overwrite or hand-edit `openclaw.json`.
5. Static validation:
   - `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 real routing verification is available, run it now. Falling back to the
   main agent, default assistant behavior, an old persona, or an ID mismatch
   means the runtime has not switched.
7. Only when static validation passes but routing verification fails, run
   **one** `openclaw gateway restart` and repeat the verification once.

Reporting: distinguish "config written and statically valid" from "runtime
verified". If verification cannot be run, say "config has been written,
runtime not yet tested, needs the upper-level flow to continue verification".
Never echo the full `api_key` in plaintext.

## Workflow B — `create-and-bind`

Inputs: `agentName`, `introduction` (required; run the intake above);
`isMain`, `categoryId` | `categoryName`, `parentCategoryId` (default `0`),
`categorySortOrder` (optional).

1. Call `grix_admin` once with `action=create_agent` and the supplied fields.
2. Read `createdAgent.id`, `agent_name`, `api_endpoint`, `api_key` from the
   result. If a requested category was not applied, finish it with the
   category actions.
3. Continue immediately with Workflow A using those values.
4. Report remote creation and local binding as separate phases; if binding
   fails after creation succeeded, report the overall result as partial.

Fallback: if no agent parameters exist and the current account lacks
`agent.api.create`, stop and ask the owner to create the agent in the backend
admin, then run Workflow A with the parameters they provide.

## Workflow C — `category-manage`

Inputs: `operation` (`list` | `create` | `update` | `assign`) plus the fields
required by the matching action above. Map directly to `list_categories`,
`create_category`, `update_category`, `assign_category`. If the request also
creates an agent, use Workflow B instead.

## Reference

[references/api-contract.md](references/api-contract.md) — request/response
shapes for each action and the local binding checklist.