grix-connector/openclaw-plugin/skills/grix-register/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-register
description: Used only during the initial installation phase to complete Grix environment account registration/login and obtain the first provider_type=3 Agent parameters; this skill does not perform any local OpenClaw configuration.
---

# Grix Register

This skill is solely responsible for the cloud preparation during "initial installation": account registration/login + generating the first `provider_type=3` Agent parameters.  
You (AI) operate fully automatically in the terminal, **without requiring the user to open a browser**. After obtaining the parameters, you must hand off to `grix-admin` for local configuration and runtime convergence through `grix_admin`'s `task` entry.

## Workflow

### 0. Role Boundary (Declare Before Executing)

1. This skill **can only** perform account and cloud Agent parameter preparation.
2. This skill **cannot** execute `openclaw` commands or modify local `openclaw.json`.
3. Anything involving local configuration, plugin installation, tool permissions, hot-reload validation, or runtime switch verification must be handed to `grix-admin`.

### 1. Ask for Email and Send Verification Code

1. Ask the user for their email address. **Do not ask the user to register on the website**; clearly state that you will complete it within the conversation.
2. After obtaining the email, execute the verification code sending command in the terminal:
   ```bash
   node scripts/grix_auth.js send-email-code --email "<user's email>" --scene "register"
   ```
3. After the command executes successfully, prompt the user to check their inbox for the verification code and ask for it.

### 2. Execute Automatic Registration (Obtain Token)

1. After the user provides the verification code, generate a high-complexity random secure password for the user (recommended: 12-character strong password including uppercase, lowercase, numbers, and special characters).
2. Using the collected information, execute the registration command:
   ```bash
   node scripts/grix_auth.js register --email "<email>" --password "<generated random password>" --email-code "<verification code>"
   ```
3. This command returns the user's `access_token` on success. In your reply, securely **inform the user of the generated password** and suggest they save it properly.

Note: If registration indicates the email is already registered:
1. Only switch to the `node scripts/grix_auth.js login` path when the user explicitly provides their existing password
2. If the user does not have their existing password, do not guess or pretend recovery is complete; clearly tell the user to provide their existing password first, or go through a standalone password reset flow, then continue this skill

### 3. Create the First Cloud Agent Parameters

After obtaining the `access_token`, ask for the Agent name (use it directly if already available in context), then execute:

```bash
node scripts/grix_auth.js create-api-agent --access-token "<token>" --agent-name "<agent name>"
```

This step creates the first `provider_type=3` main API agent (`is_main=true`) through the backend's real API, giving it the full initial scope set. If a same-name `provider_type=3` Agent already exists, the script will automatically rotate the API Key and reuse it.

### 4. Force Handoff to grix-admin via `grix_admin.task`

After step 3 executes successfully, the script returns these key settings:
- `agent_id`
- `agent_name`
- `api_endpoint`
- `api_key`

Then immediately call `grix_admin`, but **do not** pass these fields directly as `grix_admin`'s typed params. The correct approach is to write them into the `task` text, letting `grix-admin` enter the `bind-local` flow.

Recommended `task` format:

```text
bind-local
agent_name=<agent_name>
agent_id=<agent_id>
api_endpoint=<api_endpoint>
api_key=<api_key>
do_not_create_remote_agent=true
```

If the script output already includes `handoff.task`, prefer reusing that `task` directly. Before `grix-admin` actually completes, do not describe the local side as already configured or activated.

## Guardrails

1. Do not ask the user to register on the website or manually click pages.
2. Do not modify any local OpenClaw configuration.
3. Do not install plugins, change tool permissions, or restart the gateway.
4. After creating or reusing parameters, must hand off to `grix-admin`.
5. Do not claim local completion or activation; local completion state is determined by `grix-admin`.

## References

1. [references/api-contract.md](references/api-contract.md)
2. [references/handoff-contract.md](references/handoff-contract.md)
3. [scripts/grix_auth.js](scripts/grix_auth.js)