grix-connector/openclaw-plugin/skills/grix-admin/SKILL.md

Connect local AI coding agents (Claude, Codex, Gemini, Qwen, DeepSeek, Cursor, OpenCode, Pi, OpenHuman, Reasonix) to the Grix scheduling platform. Also serves as an OpenClaw plugin for Grix channel transport.

---
name: grix-admin
description: Responsible for OpenClaw local configuration, binding, and runtime convergence; can create new remote API agents through the current agent's WS channel, and supports querying, creating, modifying agent categories and assigning categories to agents, reusable across agent creation and management flows.
---

# Grix Agent Admin

`grix-admin` is responsible for three things:

1. Landing existing remote agent parameters into local OpenClaw, and handling runtime convergence after binding.
2. When the current main agent is already online and has the corresponding scope, creating new remote API agents through `grix_admin`'s direct actions, then continuing with local landing.
3. During agent creation or subsequent agent management, reusing `grix_admin`'s direct actions to query categories, create categories, modify categories, and assign categories to agents.

## Entry Method

1. In most cases, enter this skill from `grix_admin`'s `task` entry; the first line of `task` must clearly state `bind-local`, `create-and-bind`, or `category-manage`.
2. Only when executing "remote API agent creation / category query / category creation / category modification / category assignment" remote steps within this skill should you directly call `grix_admin` once, without passing `task` again.
3. In new flows, always explicitly pass `action` when directly calling `grix_admin`:
   - `create_agent`
   - `list_categories`
   - `create_category`
   - `update_category`
   - `assign_category`
4. The legacy direct call format for `create_agent` (passing only `agentName` and other fields without `action`) is still compatible, but should not be used in new flows.

## Direct Action List

1. `action=create_agent`
   - Required: `agentName`
   - Optional: `introduction`, `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder`
   - `categoryId` and `categoryName` cannot be provided simultaneously
   - When `categoryName` is given, it first checks for duplicates under `parentCategoryId`; if not found, creates and assigns
2. `action=list_categories`
   - Required: (none)
3. `action=create_category`
   - Required: `name`, `parentId`
   - Optional: `sortOrder`
4. `action=update_category`
   - Required: `categoryId`, `name`, `parentId`
   - Optional: `sortOrder`
5. `action=assign_category`
   - Required: `agentId`, `categoryId`
   - `categoryId=0` means clear the category

## Mode A: bind-local (Initial Handoff from grix-register)

Input fields (written in `grix_admin.task`, all required):

1. First line must be `bind-local`
2. `agent_name`
3. `agent_id`
4. `api_endpoint`
5. `api_key`

Execution rules:

1. Do not perform remote creation; execute local binding directly. Do not call any script that directly modifies `openclaw.json`.
2. Prepare local directories first:
   - `workspace=~/.openclaw/workspace-<agent_name>`
   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
   - Persona files go only in the `workspace` root: `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, and optionally `USER.md` / `MEMORY.md`
   - Do not put persona files in `agentDir`; `agentDir` is the per-agent runtime state directory managed by OpenClaw
   - If `workspace` is missing required persona files, add minimal files to avoid an empty workspace for the new agent
3. Read existing configuration; if paths do not exist, treat as empty object / empty array:
   - `channels.grix.accounts`
   - `agents.list`
   - `tools.profile`
   - `tools.alsoAllow`
   - `tools.sessions.visibility`
   - To confirm existing Grix bindings, additionally use `openclaw agents bindings --agent <agent_name> --json` to view the current binding list
4. Calculate target values for this operation:
   - `channels.grix.accounts.<agent_name>`: write `name`, `enabled=true`, `apiKey`, `wsUrl`, `agentId`
   - `agents.list`: ensure entry exists with `id=<agent_name>`, `name=<agent_name>`, `workspace`, `agentDir`, `model`
   - Grix binding: ensure the target agent is ultimately bound to `grix:<agent_name>`
   - `tools.profile`: set to `"coding"`
   - `tools.alsoAllow`: must include at least `message`, `grix_query`, `grix_group`, `grix_register`, `grix_message_send`, `grix_message_unsend`
   - If the current binding target is the main agent, also ensure that agent's own `tools.alsoAllow` retains `grix_admin`, `grix_egg`, `grix_update`, `openclaw_memory_setup`; this set goes only at the agent level, not in global `tools.alsoAllow`
   - `tools.sessions.visibility`: set to `"agent"`
   - If `channels.grix.enabled=false`, change it back to `true`
5. Rules for determining `model`:
   - First reuse the existing `model` from that local agent's entry
   - If the existing entry has none, use `agents.defaults.model.primary`
   - If still unavailable, clearly state that model is missing, stop execution, do not guess
6. Write using official CLI item by item; do not overwrite the entire config:
   - `openclaw config set channels.grix.accounts.<agent_name> '<ACCOUNT_JSON>' --strict-json`
   - `openclaw config set agents.list '<NEXT_AGENTS_LIST_JSON>' --strict-json`
   - `openclaw agents bind --agent <agent_name> --bind grix:<agent_name>`
   - `openclaw config set tools.profile '"coding"' --strict-json`
   - `openclaw config set tools.alsoAllow '["message","grix_query","grix_group","grix_register","grix_message_send","grix_message_unsend"]' --strict-json`
   - If the current binding target is the main agent, also merge `grix_admin`, `grix_egg`, `grix_update`, `openclaw_memory_setup` into that agent's own `agents.list` record's `tools.alsoAllow`; do not put this set in global `tools.alsoAllow`
   - `openclaw config set tools.sessions.visibility '"agent"' --strict-json`
   - Only when the current config explicitly has `channels.grix.enabled` turned off, execute `openclaw config set channels.grix.enabled true --strict-json`
7. After writing, must perform 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`
8. If this invocation already has real verification conditions, must immediately perform a real routing verification; prefer reusing the current install/acceptance context, do not invent a new probe. The following situations are all considered as binding runtime not yet switched successfully:
   - Reply falls to the main agent
   - Reply behaves as the default assistant
   - Reply still shows old persona, old config, or obvious ID mismatch
9. Only when this `bind-local` invocation itself handles real verification, and step 7 static validation passed but step 8 real routing verification still fails, is one `openclaw gateway restart` allowed as targeted remediation; after restart, must redo the same round of real routing verification.
10. Success definition:
    - Can perform real verification: only "static validation passed + real routing verification passed" counts as `bind-local` complete
    - This invocation cannot yet perform real verification: can only clearly state "config has been written, runtime not yet tested, needs subsequent upper-level flow to continue verification"; do not claim it has fully taken effect

## Mode B: create-and-bind (Subsequent Management When Main Channel and Scope Are Available)

Fields written in `grix_admin.task`:

1. First line must be `create-and-bind`
2. `agentName` (required)
3. `introduction` (optional)
5. `isMain` (optional, default `false`)
6. `categoryId` (optional): assign the new agent directly to an existing category
7. `categoryName` (optional): create if not exists, then assign
8. `parentCategoryId` (optional): only used in the `categoryName` approach, default `0`
9. `categorySortOrder` (optional): only used when creating a category

Execution rules:

1. Confirm the current session is bound to a valid Grix account; cross-account execution is prohibited.
2. If both `categoryId` and `categoryName` are provided, report an error and stop immediately to avoid ambiguity.
3. Call `grix_admin` only once with `action=create_agent`, delegating remote creation and optional category handling to it; pass:
   - `action=create_agent`
   - `agentName`
   - Optional `introduction`
   - Optional `isMain`
   - Optional `categoryId`
   - Optional `categoryName`
   - Optional `parentCategoryId`
   - Optional `categorySortOrder`
4. After remote creation succeeds, read `createdAgent.id`, `createdAgent.agent_name`, `createdAgent.api_endpoint`, `createdAgent.api_key` from the return result.
5. If the request included category information, check whether the return already includes the category assignment result; if not, proceed with supplementary steps according to `categoryId` / `categoryName` rules and explain the reason.
6. In the `categoryName` flow, if multiple categories with the exact same name appear under the same parent, stop and ask the owner to clean up categories or use an explicit `categoryId` instead.
7. After remote creation and optional category steps succeed, immediately transition to the `bind-local` local binding steps; if this invocation already has real verification context, follow the same "static validation -> real routing verification -> one restart if needed -> same-round retest" convergence rules; otherwise explicitly hand the "continue real verification" responsibility back to the upper-level flow.
8. `isMain=true` should only be used when actually creating a new main API agent; generally subsequent new agents should not enable this by default.
9. Throughout the `create-and-bind` flow, do not treat "config written successfully" as completion; only when this invocation itself handles real routing verification and verification fails should one `openclaw gateway restart` be treated as targeted remediation.

## Mode C: category-manage (Category Management)

Fields written in `grix_admin.task`:

1. First line must be `category-manage`
2. `operation` (required): only `list`, `create`, `update`, `assign` are allowed
4. `name` (`create` / `update` required)
5. `parentId` (`create` / `update` required)
6. `sortOrder` (`create` / `update` optional)
7. `categoryId` (`update` / `assign` required; for `assign`, `0` means clear)
8. `agentId` (`assign` required)

Execution rules:

1. Strictly bound to the current session account; cross-account execution is prohibited.
2. All remote steps must only be completed through `grix_admin`'s direct actions; hand-written HTTP and temporary scripts are prohibited.
3. `operation=list`
   - Call `action=list_categories`
4. `operation=create`
   - Call `action=create_category`
5. `operation=update`
   - Call `action=update_category`
6. `operation=assign`
   - Call `action=assign_category`
   - `categoryId=0` explicitly means clear the agent's current category
7. If the current management task also includes "creating a new agent", prefer using `create-and-bind`; do not split remote creation into other custom flows.

## Remote Creation Fallback Conditions

If the current task has neither an existing `agent_name`, `agent_id`, `api_endpoint`, `api_key`, nor an available online main channel or `agent.api.create` permission, stop this skill first and clearly prompt the user to create the remote agent through the backend admin path. After obtaining these parameters, proceed with `bind-local`.

## Guardrails (Applicable to All Three Modes)

1. Never ask user for website account/password.
2. `bind-local` mode must not call back to `grix-register` to avoid circular routing.
3. All remote creation / category-related actions must only go through `grix_admin` direct actions via the current account's WS channel; do not hand-write HTTP or fall back to legacy scripts.
4. The complete `api_key` is only passed back once; do not repeatedly echo it in plaintext.
5. Before local `openclaw config set` / `validate` succeeds, do not claim config is complete; when this invocation can perform real verification, do not claim `bind-local` / `create-and-bind` is complete until real routing verification passes.
6. During an install private chat, do not manually modify `openclaw.json` and then execute `openclaw gateway restart`.
7. Do not reference or call `grix_agent_bind.py`; this skill only uses official OpenClaw config commands.

## Error Handling Rules

1. `bind-local` missing fields: clearly state which field is missing and stop.
2. `create-and-bind` missing `agentName`: clearly state which field is missing and stop.
3. `create-and-bind` with both `categoryId` and `categoryName`: clearly state the conflict and stop.
4. `category-manage` missing `operation` or operation-specific fields: clearly state which field is missing and stop.
5. Remote returns `code=4003` or message explicitly mentions `agent.api.create`: tell the owner to grant `agent.api.create` on the Agent permissions page.
6. Remote returns `code=4003` or message explicitly mentions `agent.category.list` / `agent.category.create` / `agent.category.update` / `agent.category.assign`: tell the owner to grant the corresponding scope on the Agent permissions page.
7. Missing remote agent parameters and current account cannot create: clearly require backend admin creation first.
8. Local config failure: return the failed command and result, then stop; emphasize which `get` / `set` / `validate` step failed.
9. This invocation handles real routing verification, and after one `openclaw gateway restart` retest still fails: clearly state "static config has been written, but runtime has not yet switched successfully"; converge as failed or partially complete, do not write it as success.

## Response Style

1. Clearly state whether the current execution is `bind-local`, `create-and-bind`, or `category-manage`.
2. Report in phases: remote creation / category handling (if any) / local config writing / validation results.
3. Clearly state whether local config has taken effect; if only static config succeeded but this invocation cannot perform real verification, can only write "config has been written, runtime not yet tested, needs subsequent flow to continue verification"; if only the category step succeeded, also state that clearly.
4. If remote creation succeeded but category or local binding subsequently failed, clearly state it is "partially complete"; do not generically write it as success.

## References

1. [references/api-contract.md](references/api-contract.md)