grix-connector 3.3.5 → 3.5.0

package/README.md

@@ -4,7 +4,9 @@ A command-line daemon that connects your local AI coding agents to the [Grix](ht
 
 ## What is Grix?
 
-Grix is an AI Agent scheduling platform. It lets you manage and interact with multiple AI coding agents through a unified chat interface. Register at [grix.im](https://grix.im) to get started.
+Grix is an AI Agent scheduling platform. It lets you manage and interact with multiple AI coding agents through a unified chat interface.
+
+> **Reading this as an AI agent doing the install?** Everything here is terminal-only. Account registration included — you collect the user's email and the emailed verification code in chat and call the API yourself ([step 1](#1-register-a-grix-account-and-create-an-agent)). Never send the user off to a website to sign up.
 
 ## Get the Client
 
@@ -45,11 +47,134 @@ Requires Node.js >= 18.
 
 On Windows, `grix-connector` uses the built-in Task Scheduler with a hidden WScript launcher (no extra dependency required).
 
+### After the install: you still need a Grix account
+
+Installing the CLI is not enough — the daemon refuses to start without a Grix account and an agent credential. The install is step 0 of four:
+
+1. **Register a Grix account.** This is where you need the user: **ask them for an email address**, because a verification code is mailed to it and they have to read it back to you. → [step 1](#1-register-a-grix-account-and-create-an-agent)
+2. Create the agent and collect `agent_id` / `api_key` / `ws_url`. → [step 1.4](#14-create-the-api-agent)
+3. Write `~/.grix/config/agents.json`. → [step 2](#2-create-agent-config)
+4. `grix-connector start`. → [step 3](#3-start-the-daemon)
+
+So the very first thing to ask the user for, right after the install, is **an email address**.
+
+The registration flow is also packaged as a skill, `grix-register`. In OpenClaw plugin mode it is loaded automatically; after a global npm install any agent can read it directly:
+
+```bash
+cat "$(npm root -g)/grix-connector/openclaw-plugin/skills/grix-register/SKILL.md"
+```
+
+Running that skill and following step 1 below are the same thing — the same API calls, described once as a skill and once as plain curl. Use whichever your runtime supports.
+
 ## Quick Start
 
-### 1. Register a Grix account
+### 1. Register a Grix account and create an agent
+
+This whole step is HTTP API calls — no browser, no dashboard. The user only has to give you two things in chat: **their email address**, and **the 6-digit verification code** that lands in their inbox. You do the rest.
+
+**API base:** `https://grix.dhf.pub/v1` — this is the auth/agent API for both regions (`ws.grix.im` serves the WebSocket only, it has no auth routes). A private deployment replaces the host.
+
+**Response envelope:** every endpoint returns `{"code": 0, "msg": "success", "data": {...}}`. A HTTP 200 with a non-zero `code` is still a failure — always branch on `code`, not on the HTTP status.
+
+#### 1.1 Ask for the email, send the verification code
+
+Ask the user for the email address they want the account under, then:
+
+```bash
+curl -s -X POST https://grix.dhf.pub/v1/auth/send-code \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"<user-email>","scene":"register"}'
+```
+
+On `code: 0`, tell the user to check their inbox (and the spam folder) and ask them to paste the 6-digit code back to you.
+
+| `code` | Meaning | What to do |
+|---|---|---|
+| `10003` | Invalid parameter — the email failed validation | Re-check the address with the user |
+| `10005` | Rate limited: a code was already sent | Do **not** retry in a loop. Tell the user to wait ~5 minutes, or ask them for the code that was already sent |
+
+#### 1.2 Register
+
+**Generate the password yourself** — do not make the user invent one. Use a random 12+ character password mixing upper case, lower case, digits and symbols. Then:
+
+```bash
+curl -s -X POST https://grix.dhf.pub/v1/auth/register \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "email": "<user-email>",
+    "password": "<generated-password>",
+    "email_code": "<code the user gave you>",
+    "device_id": "cli_<random-uuid>",
+    "platform": "cli"
+  }'
+```
+
+Returns `data.access_token` (plus `refresh_token`, `expires_in`, `user.id`). Keep the token in memory for the next call.
+
+**After a successful registration, show the user the generated password and tell them to save it** — it is their account password and it is not recoverable from anywhere else.
+
+Failures you will actually hit — note that both of them come back as `code: 10001`, so **read the `msg`, not just the code**:
+
+| `msg` | Meaning | What to do |
+|---|---|---|
+| `邮箱验证码错误或已过期` (code wrong or expired) | The code really is wrong | Ask the user to re-read it, or re-send it (1.1) |
+| `注册失败，请检查邮箱验证码后重试` (registration failed, check the code) | **Almost always: the email is already registered.** The message blames the code, but the code already passed validation | Do **not** re-send the code in a loop — go to 1.3 and log in |
+
+#### 1.3 Existing account — log in instead
+
+Only when the user **gives you their existing password**:
+
+```bash
+curl -s -X POST https://grix.dhf.pub/v1/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"account":"<user-email>","password":"<password>","device_id":"cli_<random-uuid>","platform":"cli"}'
+```
+
+Same `data.access_token` as register. If the user does not remember their password, do not guess and do not pretend to recover it — ask them to reset it in the Grix client, then come back with the password.
+
+#### 1.4 Create the API agent
+
+This is where `agent_id` and `api_key` come from. Ask the user what to name the agent (or reuse a name already agreed in the conversation):
+
+```bash
+curl -s -X POST https://grix.dhf.pub/v1/agents/create \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <access_token>' \
+  -d '{"agent_name":"<agent-name>","provider_type":3,"is_main":true}'
+```
+
+`provider_type: 3` is the Agent API type — the only type this connector can drive. `is_main: true` gives the first agent the full initial permission scope.
+
+Returns in `data`:
+
+| Field | Use |
+|---|---|
+| `id` | the `agent_id` for your config |
+| `api_key` | the `api_key` for your config — **shown exactly once, it is never retrievable again** |
+| `api_endpoint` | the `ws_url` for your config |
+| `api_key_hint` | last few characters, for later identification |
+
+**If the name is already taken** by a `provider_type: 3` agent, reuse it instead of inventing a new name — list the agents, find the exact-name entry with `provider_type == 3` and `status != 3`, and rotate its key:
+
+```bash
+curl -s -H 'Authorization: Bearer <access_token>' https://grix.dhf.pub/v1/agents/list
+
+curl -s -X POST -H 'Authorization: Bearer <access_token>' \
+  -H 'Content-Type: application/json' \
+  https://grix.dhf.pub/v1/agents/<agent-id>/api/key/rotate -d '{}'
+```
+
+Rotation returns a fresh `api_key` and the same `api_endpoint`. The old key stops working immediately, so only rotate an agent the user actually wants to re-point at this machine.
+
+#### 1.5 Map the fields into the config
+
+| From the API | Into `agents.json` |
+|---|---|
+| `data.id` | `agent_id` |
+| `data.api_key` | `api_key` |
+| `data.api_endpoint` | `ws_url` — drop any `?agent_id=…` query string, keep only the part before `?` |
 
-Go to [grix.im](https://grix.im), sign up and get your API key.
+If `api_endpoint` comes back empty, fall back to the regional URL in step 2. Write the `api_key` into `~/.grix/config/agents.json` and nowhere else — never into a log, a shell history file, or a repository.
 
 ### 2. Create agent config
 
@@ -298,7 +423,7 @@ Finally send a message to the agent from Grix and confirm the reply really comes
 ### Requirements
 
 - OpenClaw >= 2026.4.8
-- A Grix account with agent ID and API key
+- A Grix account with agent ID and API key — get them with the API flow in [step 1](#1-register-a-grix-account-and-create-an-agent); it works the same in plugin mode
 
 Plugin mode and the standalone daemon can coexist on one machine — they use separate configs and separate processes. Do not, however, bring the **same** `agent_id` online in both at once; give each mode its own agent.