@dhf-openclaw/grix 0.4.10 → 0.4.11

package/README.md

@@ -1,75 +1,46 @@
-# OpenClaw Grix Unified Plugin
+# OpenClaw Grix 插件
 
-This plugin connects OpenClaw to [https://grix.dhf.pub/](https://grix.dhf.pub/) and provides a single, unified integration for:
+把 OpenClaw 接到 Grix（`grix.dhf.pub`）的统一插件，包含：
 
-- Grix channel transport (WebSocket Agent API)
-- native message actions (`unsend` / `delete`)
-- typed Grix admin tools
-- operator CLI commands
-- bundled Grix workflow skills
+- Grix Channel（收发消息、流式回复、`unsend`、`delete`）
+- 管理工具：`grix_query`、`grix_group`、`grix_agent_admin`
+- 运维命令：`openclaw grix doctor`、`openclaw grix create-agent`
+- 内置技能包（`skills/`）
 
-Compatibility:
+## 兼容性
 
-- Requires `OpenClaw >= 2026.3.13`
+- `OpenClaw >= 2026.3.23-1`
 
-## Included Capability
+## 5 分钟安装（推荐）
 
-After installation, one plugin covers all major Grix workflows:
-
-- Channel runtime:
-  - inbound message receive
-  - outbound reply / media / streaming chunk send
-  - native channel actions (`unsend`, `delete`)
-- Typed admin tools:
-  - `grix_query`
-  - `grix_group`
-  - `grix_agent_admin`
-- Operator CLI:
-  - `openclaw grix doctor`
-  - `openclaw grix create-agent ...`
-- Bundled skills:
-  - `message-send`
-  - `message-unsend`
-  - `egg-install`
-  - `grix-query`
-  - `grix-group-governance`
-  - `grix-agent-admin`
-
-## Install
+### 1) 安装并启用插件
 
 ```bash
 openclaw plugins install @dhf-openclaw/grix
 openclaw plugins enable grix
-openclaw gateway restart
 ```
 
-### Local Source Checkout
+### 2) 绑定 Grix Channel
 
-If you load from a local checkout:
+用你已有的 Grix API agent 信息执行：
 
 ```bash
-npm install
-openclaw plugins install ./grix.ts
+openclaw channels add \
+  --channel grix \
+  --name grix-main \
+  --http-url "wss://grix.dhf.pub/v1/agent-api/ws?agent_id={agent_id}" \
+  --user-id "<YOUR_AGENT_ID>" \
+  --token "<YOUR_API_KEY>"
 ```
 
-## Required OpenClaw Config
+说明：
 
-### Channel Config (`channels.grix`)
+- `--http-url` 可以带 `agent_id`，也可以不带。不带时会自动按 `--user-id` 补上。
+- `--name` 是本地账户名，可自定义（如 `ops`、`prod`）。
 
-```json
-{
-  "channels": {
-    "grix": {
-      "enabled": true,
-      "wsUrl": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>",
-      "agentId": "<YOUR_AGENT_ID>",
-      "apiKey": "<YOUR_API_KEY>"
-    }
-  }
-}
-```
+### 3) 开放工具权限
 
-### Tool Exposure Config
+在 OpenClaw 配置里确保有：
 
 ```json
 {
@@ -88,7 +59,31 @@ openclaw plugins install ./grix.ts
 }
 ```
 
-Full example:
+### 4) 重启网关
+
+```bash
+openclaw gateway restart
+```
+
+### 5) 验证安装结果
+
+```bash
+openclaw plugins info grix --json
+openclaw grix doctor
+openclaw skills list
+```
+
+预期：
+
+- `grix` 插件已启用
+- `doctor` 能看到可用账户
+- `skills list` 能看到本插件内置技能
+
+## 配置参数说明（完整）
+
+`channels.grix` 支持“单账户”或“多账户（accounts）”两种写法。
+
+### 最小可用配置（单账户）
 
 ```json
 {
@@ -99,66 +94,92 @@ Full example:
       "agentId": "<YOUR_AGENT_ID>",
       "apiKey": "<YOUR_API_KEY>"
     }
-  },
-  "tools": {
-    "profile": "coding",
-    "alsoAllow": [
-      "message",
-      "grix_query",
-      "grix_group",
-      "grix_agent_admin"
-    ],
-    "sessions": {
-      "visibility": "agent"
-    }
   }
 }
 ```
 
-After any config change:
+### 多账户配置示例
 
-```bash
-openclaw gateway restart
+```json
+{
+  "channels": {
+    "grix": {
+      "enabled": true,
+      "defaultAccount": "ops",
+      "accounts": {
+        "ops": {
+          "enabled": true,
+          "name": "Ops",
+          "wsUrl": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=<OPS_AGENT_ID>",
+          "agentId": "<OPS_AGENT_ID>",
+          "apiKey": "<OPS_API_KEY>"
+        },
+        "prod": {
+          "enabled": true,
+          "wsUrl": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=<PROD_AGENT_ID>",
+          "agentId": "<PROD_AGENT_ID>",
+          "apiKey": "<PROD_API_KEY>"
+        }
+      }
+    }
+  }
+}
 ```
 
-## Typed Tools
-
-### `grix_query`
-
-Supported actions:
-
-- `contact_search`
-- `session_search`
-- `message_history`
-
-### `grix_group`
-
-Supported actions:
-
-- `create`
-- `detail`
-- `add_members`
-- `remove_members`
-- `update_member_role`
-- `update_all_members_muted`
-- `update_member_speaking`
-- `dissolve`
-
-### `grix_agent_admin`
-
-Creates `provider_type=3` API agents with typed parameters.
-
-This tool creates the remote Grix API agent only. It does not directly mutate local OpenClaw channel config.
-
-## Operator CLI
-
-### Inspect Grix accounts
+### 字段说明
+
+| 字段 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `enabled` | 否 | `true` | 全局开关。设为 `false` 后该通道停用。 |
+| `defaultAccount` | 否 | 自动选择 | 多账户时默认账户 ID。 |
+| `accounts.<id>` | 否 | - | 多账户配置项，`<id>` 自定义（如 `ops`）。 |
+| `name` | 否 | - | 账户显示名。 |
+| `wsUrl` | 是（可用环境变量兜底） | `ws://127.0.0.1:27189/...`（当有 `agentId` 且未填时） | Grix WebSocket 地址。 |
+| `agentId` | 是（可用环境变量兜底） | - | Grix agent ID。 |
+| `apiKey` | 是（可用环境变量兜底） | - | Grix API Key。 |
+| `reconnectMs` | 否 | `2000` | 重连基础延迟（毫秒）。 |
+| `reconnectMaxMs` | 否 | `max(30000, reconnectMs*8)` | 重连最大延迟（毫秒）。 |
+| `reconnectStableMs` | 否 | `30000` | 连接保持多久算“稳定”（毫秒）。 |
+| `connectTimeoutMs` | 否 | `10000` | 建连超时（毫秒）。 |
+| `keepalivePingMs` | 否 | 自动计算 | 心跳发送间隔（毫秒）。 |
+| `keepaliveTimeoutMs` | 否 | 自动计算 | 心跳超时阈值（毫秒）。 |
+| `upstreamRetryMaxAttempts` | 否 | `3` | 上游发送失败重试次数（1-5）。 |
+| `upstreamRetryBaseDelayMs` | 否 | `300` | 上游重试基础延迟（毫秒）。 |
+| `upstreamRetryMaxDelayMs` | 否 | `2000` | 上游重试最大延迟（毫秒）。 |
+| `maxChunkChars` | 否 | `1200` | 普通回复分片长度上限（最大 2000）。 |
+| `streamChunkChars` | 否 | `48` | 流式回复分片长度上限（最大 2000）。 |
+| `streamChunkDelayMs` | 否 | `0` | 流式分片发送间隔（毫秒）。 |
+| `dmPolicy` | 否 | `open` | 私聊策略：`open` / `pairing` / `allowlist` / `disabled`。 |
+| `allowFrom` | 否 | `[]` | 白名单发送者列表（配合 `dmPolicy=allowlist`）。 |
+| `defaultTo` | 否 | - | 默认发送目标会话。 |
+| `execApprovals.enabled` | 否 | `false` | 是否启用聊天内执行审批。 |
+| `execApprovals.approvers` | 条件必填 | `[]` | 审批人 sender ID 列表。启用审批时需填写。 |
+
+### 环境变量兜底
+
+如果配置文件没填，插件会按下列环境变量读取：
+
+- `GRIX_WS_URL`
+- `GRIX_AGENT_ID`
+- `GRIX_API_KEY`
+
+## 工具与命令
+
+### Agent 可调用工具
+
+- `grix_query`：`contact_search`、`session_search`、`message_history`
+- `grix_group`：`create`、`detail`、`add_members`、`remove_members`、`update_member_role`、`update_all_members_muted`、`update_member_speaking`、`dissolve`
+- `grix_agent_admin`：创建 `provider_type=3` 的 Grix API agent（只创建远端 agent，不会直接改本地 `channels.grix`）
+
+### 运维命令
+
+查看账户：
 
 ```bash
 openclaw grix doctor
 ```
 
-### Create API agent
+创建 API agent：
 
 ```bash
 openclaw grix create-agent \
@@ -166,19 +187,18 @@ openclaw grix create-agent \
   --describe-message-tool '{"actions":["unsend","delete"]}'
 ```
 
-`create-agent` prints:
+参数说明：
 
-- created agent payload
-- one-time API key in result payload
-- safe next-step channel binding command template
+- `--agent-name`：必填，小写字母开头，只允许小写字母、数字、`-`，长度 3-32。
+- `--describe-message-tool`：必填，JSON 对象，至少包含 `actions` 数组。
+- `--account-id`：可选，指定用哪个本地 Grix 账户发起创建。
+- `--avatar-url`：可选，给新 agent 设置头像地址。
 
-`--describe-message-tool` is required and must follow OpenClaw `describeMessageTool` discovery structure.
+命令输出里会给出一次性 `api_key` 和下一步绑定命令模板。
 
-## Exec Approvals
+## 聊天内 Exec 审批（可选）
 
-Grix can approve OpenClaw host `exec` requests in chat.
-
-### 1. Configure Grix approvers
+先在 Grix 账户里配置审批人：
 
 ```json
 {
@@ -193,26 +213,7 @@ Grix can approve OpenClaw host `exec` requests in chat.
 }
 ```
 
-If using named accounts:
-
-```json
-{
-  "channels": {
-    "grix": {
-      "accounts": {
-        "ops": {
-          "execApprovals": {
-            "enabled": true,
-            "approvers": ["<GRIX_SENDER_ID>"]
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### 2. Enable OpenClaw exec approvals
+再开启 OpenClaw 的 exec 审批：
 
 ```json
 {
@@ -228,58 +229,18 @@ If using named accounts:
       "enabled": true,
       "mode": "session"
     }
-  },
-  "channels": {
-    "grix": {
-      "execApprovals": {
-        "enabled": true,
-        "approvers": ["<GRIX_SENDER_ID>"]
-      }
-    }
   }
 }
 ```
 
-Mode choices:
+`mode` 说明：
 
-- `session`: send approval prompt to current Grix chat
-- `targets`: send approval prompt to configured `approvals.exec.targets`
-- `both`: send to both
+- `session`：发到当前会话
+- `targets`：发到 `approvals.exec.targets`
+- `both`：两边都发
 
-### 3. Restart
+配置改完后重启：
 
 ```bash
 openclaw gateway restart
 ```
-
-### 4. Approve in chat
-
-Flow:
-
-1. Ask OpenClaw to run an `exec` command that needs approval.
-2. OpenClaw sends approval prompt to Grix.
-3. An allowed approver can:
-   - click `Allow Once`, `Allow Always`, or `Deny`
-   - or send `/approve <id> allow-once|allow-always|deny`
-4. OpenClaw continues or denies execution.
-
-Notes:
-
-- approvers must be Grix sender IDs, not OpenClaw agent IDs
-- configure approvers under the serving account
-- approval requests and results are posted in chat
-
-## Verification
-
-```bash
-openclaw plugins info grix --json
-openclaw skills list
-openclaw grix doctor
-```
-
-Expected:
-
-- plugin `grix` is enabled and loaded
-- typed tools are callable when `tools.alsoAllow` is configured
-- bundled skills are visible in skills list
-- `openclaw grix doctor` can read configured `channels.grix` accounts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhf-openclaw/grix",
-  "version": "0.4.10",
+  "version": "0.4.11",
   "description": "Unified Grix OpenClaw plugin with channel transport, typed admin tools, and operator CLI",
   "type": "module",
   "main": "./dist/index.js",

package/skills/grix-admin/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: grix-admin
+description: 负责 OpenClaw 本地配置与后续 agent 管理；支持接收 grix-register 交接参数直接落地，也支持在已有主密钥下新建 agent 再落地。
+---
+
+# Grix Agent Admin
+
+`grix-admin` 只负责本地配置和管理动作。支持两个入口模式，二选一执行。
+
+## Mode A: bind-local（来自 grix-register 的首次交接）
+
+输入参数（全必填）：
+
+1. `mode=bind-local`
+2. `agent_name`
+3. `agent_id`
+4. `api_endpoint`
+5. `api_key`
+
+执行规则：
+
+1. 不做远端创建，直接执行本地绑定：
+
+```bash
+scripts/grix_agent_bind.py configure-local-openclaw \
+  --agent-name <agent_name> \
+  --agent-id <agent_id> \
+  --api-endpoint '<api_endpoint>' \
+  --api-key '<api_key>' \
+  --apply
+```
+
+2. 可选执行检查：
+
+```bash
+scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>
+```
+
+## Mode B: create-and-bind（已有主密钥时的后续管理）
+
+输入参数：
+
+1. `agentName`（必填）：`^[a-z][a-z0-9-]{2,31}$`
+2. `describeMessageTool`（必填）：`actions` 非空
+3. `accountId`（可选）
+4. `avatarUrl`（可选）
+
+执行规则：
+
+1. 先检查 `~/.openclaw/openclaw.json` 的 `channels.grix.apiKey`。
+2. 若缺失或为空，说明主通道还没完成，不做本模式，立刻切回 `grix-register`。
+3. 若已存在，再调用 `grix_agent_admin` 创建远端 agent（仅一次，不自动重试）。
+4. 创建成功后，执行本地绑定命令（同 Mode A）。
+
+## Guardrails（两种模式都适用）
+
+1. Never ask user for website account/password.
+2. `bind-local` 模式禁止再次回调 `grix-register`，避免循环路由。
+3. 远端创建（Mode B）视为非幂等，不确认不自动重试。
+4. 完整 `api_key` 仅一次性回传，不要重复明文回显。
+5. 本地 `--apply` 没成功前，不得宣称配置完成。
+
+## Error Handling Rules
+
+1. `bind-local` 缺少字段：明确指出缺哪个字段并停止。
+2. invalid name（Mode B）：要求用户提供合法小写英文名。
+3. `403/20011`：提示 owner 授权 `agent.api.create`。
+4. `401/10001`：检查本地 `agent_api_key` 或 grix 账号配置。
+5. `409/20002`：要求更换 agent 名称。
+6. 本地 apply 失败：返回失败命令与结果并停止。
+
+## Response Style
+
+1. 明确写出当前执行的是 `bind-local` 还是 `create-and-bind`。
+2. 分阶段汇报：远端（如有）+ 本地绑定。
+3. 明确说明本地是否已生效，失败则给具体原因。
+
+## References
+
+1. [references/api-contract.md](references/api-contract.md)
+2. [scripts/grix_agent_bind.py](scripts/grix_agent_bind.py)

package/skills/{grix-agent-admin → grix-admin}/references/api-contract.md

@@ -2,7 +2,10 @@
 
 ## Purpose
 
-Map remote provisioning action to Aibot Agent API HTTP route, then hand over to local OpenClaw binding.
+`grix-admin` 负责本地绑定，支持两种入口：
+
+1. `bind-local`：接收 `grix-register` 交接参数，直接本地绑定。
+2. `create-and-bind`：在已有主密钥下先远端创建，再本地绑定。
 
 ## Base Rules
 
@@ -12,7 +15,7 @@ Map remote provisioning action to Aibot Agent API HTTP route, then hand over to
 4. Route must pass scope middleware before service business checks.
 5. Do not ask users to provide website account/password for this flow.
 
-## Action Mapping (v1)
+## Action Mapping (create-and-bind only)
 
 | Tool | Method | Route | Required Scope |
 |---|---|---|---|
@@ -72,7 +75,7 @@ Map remote provisioning action to Aibot Agent API HTTP route, then hand over to
 
 ## Post-Create Handover
 
-After `code=0`, continue with local OpenClaw binding via bundled script:
+After `code=0` (or when using `bind-local` mode), continue with local OpenClaw binding via bundled script:
 
 1. apply local changes directly:
    - `scripts/grix_agent_bind.py configure-local-openclaw --agent-name <agent_name> --agent-id <agent_id> --api-endpoint '<api_endpoint>' --api-key '<api_key>' --apply`
@@ -85,3 +88,19 @@ Local apply writes:
 2. `channels.grix.accounts.<agent_name>` entry
 3. `bindings` route for `channel=grix`
 4. required tools config and gateway restart
+
+## bind-local Input Contract
+
+When called from `grix-register`, `grix-admin` should accept:
+
+```json
+{
+  "mode": "bind-local",
+  "agent_name": "grix-main",
+  "agent_id": "2029786829095440384",
+  "api_endpoint": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=2029786829095440384",
+  "api_key": "ak_xxx"
+}
+```
+
+In this mode, skip remote create and execute local bind directly.

package/skills/{egg-install → grix-egg}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: egg-install
+name: grix-egg
 description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 OpenClaw agent 收到包含 install_id、egg、install、main_agent 的安装上下文时，负责与用户多轮确认、执行 persona.zip 到 OpenClaw agent 或 skill.zip 到 Claude agent 的正规安装流程，并在当前私聊里持续回报进度、失败原因和最终结果。
 ---
 

package/skills/{grix-group-governance → grix-group}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: grix-group-governance
+name: grix-group
 description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, update, or dissolve groups, or when these operations fail with scope or permission errors.
 ---
 

package/skills/grix-register/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: grix-register
+description: 仅用于初次安装阶段，完成 grix.dhf.pub 账号注册/登录并拿到第一个 provider_type=3 Agent 的参数；本技能不做任何本地 OpenClaw 配置。
+---
+
+# Grix Register
+
+这个技能只负责“初次安装”的云端准备：账号注册/登录 + 生成首个 `provider_type=3` Agent 参数。  
+你（AI）在终端里全自动操作，**不需要用户打开浏览器**。拿到参数后，必须移交给 `grix-admin` 做本地配置。
+
+## Workflow
+
+### 0. 角色边界（先声明再执行）
+
+1. 本技能**只能**做账号与云端 Agent 参数准备。
+2. 本技能**不能**执行 `openclaw` 命令，也不能修改本地 `openclaw.json`。
+3. 涉及本地配置、插件安装、工具权限、重启网关，一律交给 `grix-admin`。
+
+### 1. 询问邮箱并发送验证码
+
+1. 向用户询问 Email 地址。**不要让用户去网页端注册**，明确表示你会在对话里完成。
+2. 拿到邮箱后，在终端执行发送验证码的命令：
+   ```bash
+   scripts/grix_auth.py send-email-code --email "<用户的email>" --scene "register"
+   ```
+3. 等待命令执行成功后，提示用户去邮箱查收验证码，并询问该验证码。
+
+### 2. 执行自动注册（获取 Token）
+
+1. 用户提供验证码后，你需要为用户生成一个复杂度高且随机安全的密码（建议生成一个12位的强密码，包含大小写、数字和特殊字符）。
+2. 使用收集到的信息，执行注册命令：
+   ```bash
+   scripts/grix_auth.py register --email "<邮箱>" --password "<生成的随机密码>" --email-code "<验证码>"
+   ```
+3. 这个命令成功后会返回用户的 `access_token`。请在回复中安全地**将生成的密码告知用户**，建议他们妥善保存。
+
+注：如果注册提示邮箱已注册，可切换 `scripts/grix_auth.py login` 路径继续获取 `access_token`。
+
+### 3. 创建首个云端 Agent 参数
+
+拿到 `access_token` 后，询问 Agent 名称（如果上下文已有就直接用），执行：
+
+```bash
+scripts/grix_auth.py create-api-agent --access-token "<token>" --agent-name "<agent名称>"
+```
+
+若同名 `provider_type=3` Agent 已存在，脚本会自动轮换 API Key 后复用。
+
+### 4. 强制移交给 grix-admin
+
+第三步执行成功后，脚本会返回一些关键设定：
+- `agent_id`
+- `agent_name`
+- `api_endpoint`
+- `api_key`
+
+然后立刻交给 `grix-admin`，并传递如下 payload：
+
+```json
+{
+  "mode": "bind-local",
+  "agent_name": "<agent_name>",
+  "agent_id": "<agent_id>",
+  "api_endpoint": "<api_endpoint>",
+  "api_key": "<api_key>"
+}
+```
+
+## Guardrails
+
+1. 不要求用户去网页注册或手动点页面。
+2. 不修改任何本地 OpenClaw 配置。
+3. 不安装插件、不改工具权限、不重启 gateway。
+4. 创建或复用出参数后，必须交接给 `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.py](scripts/grix_auth.py)

package/skills/grix-register/references/api-contract.md

@@ -0,0 +1,71 @@
+# API Contract
+
+## Responsibility Boundary
+
+1. `grix-register` 仅负责账号鉴权与云端 `provider_type=3` Agent 参数产出。
+2. 本技能不负责本地 OpenClaw 配置。
+3. 本地配置由 `grix-admin` 接手。
+
+## Base
+
+1. Website: `https://grix.dhf.pub/`
+2. Public Grix API base: `https://grix.dhf.pub/v1`
+
+## Route Mapping
+
+### Agent bootstrap action
+
+| Action | Method | Route | Auth |
+|---|---|---|---|
+| `create-api-agent` | `POST` | `/agents/create` | `Authorization: Bearer <access_token>` |
+| `list-agents` (internal helper) | `GET` | `/agents/list` | `Authorization: Bearer <access_token>` |
+| `rotate-api-agent-key` (internal helper) | `POST` | `/agents/:id/api/key/rotate` | `Authorization: Bearer <access_token>` |
+
+## Payloads
+
+### `create-api-agent`
+
+```json
+{
+  "agent_name": "grix-main",
+  "provider_type": 3
+}
+```
+
+`provider_type=3` means Agent API type.
+
+## Reuse flow
+
+When the same-name `provider_type=3` agent already exists, the skill should:
+
+1. read `/agents/list`
+2. find the exact-name API agent
+3. rotate its key through `/agents/:id/api/key/rotate`
+4. reuse the returned `api_endpoint` and fresh `api_key`
+
+## Success Highlights
+
+### `create-api-agent`
+
+The bundled script lifts these fields to the top level:
+
+1. `agent_id`
+2. `agent_name`
+3. `provider_type`
+4. `api_endpoint`
+5. `api_key`
+6. `api_key_hint`
+7. `session_id`
+
+## Common Errors
+
+1. create-agent or rotate-key returns missing `api_endpoint` or `api_key`
+
+## Handoff
+
+成功后输出这些字段，直接交给 `grix-admin`：
+
+1. `agent_id`
+2. `agent_name`
+3. `api_endpoint`
+4. `api_key`

package/skills/grix-register/references/grix-concepts.md

@@ -0,0 +1,26 @@
+# Grix Concepts
+
+## Canonical Explanation
+
+这个插件接入是为了在 `https://grix.dhf.pub/` 网站管理 OpenClaw，并支持移动端 PWA 页面。
+
+## Feature Highlights
+
+1. `grix-register` 负责初次账号准备与首个 agent 参数生成
+2. `grix-admin` 负责 OpenClaw 本地配置与后续管理
+3. 两者串联后，用户可在 `https://grix.dhf.pub/` 使用和管理
+
+## Default User-Facing Framing
+
+### One sentence
+
+`grix-register` 只做“注册账号并拿到第一个 agent 参数”，本地配置统一交给 `grix-admin`。
+
+### Short paragraph
+
+`grix-register` 只负责初次安装中的云端准备：注册/登录账号并生成第一个 `provider_type=3` agent 参数；随后必须把参数交给 `grix-admin`，由 `grix-admin` 负责本地 OpenClaw 配置。
+
+## After Setup
+
+1. `grix-register` 产出参数后，直接交接给 `grix-admin`。
+2. `grix-register` 不执行任何本地配置动作。

package/skills/grix-register/references/handoff-contract.md

@@ -0,0 +1,24 @@
+# Handoff Contract to grix-admin
+
+## Purpose
+
+`grix-register` 完成账号与首个 Agent 参数准备后，统一把本地配置工作交给 `grix-admin`。
+
+## Required Payload
+
+```json
+{
+  "mode": "bind-local",
+  "agent_name": "grix-main",
+  "agent_id": "2029786829095440384",
+  "api_endpoint": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=2029786829095440384",
+  "api_key": "ak_xxx"
+}
+```
+
+## Rules
+
+1. `mode` 固定为 `bind-local`。
+2. `agent_name`、`agent_id`、`api_endpoint`、`api_key` 必填。
+3. `grix-register` 只负责生成以上参数，不执行本地配置命令。
+4. 本地写入、插件处理、工具权限、gateway 重启都由 `grix-admin` 负责。

package/skills/grix-register/references/openclaw-setup.md

@@ -0,0 +1,6 @@
+# OpenClaw Setup Ownership
+
+`grix-register` 不负责 OpenClaw 本地配置。  
+所有 OpenClaw 配置相关动作（插件安装、channel 写入、tools 权限、gateway 重启）都属于 `grix-admin`。
+
+本目录保留此文件仅用于职责说明，避免误用。

package/skills/grix-register/references/user-replies.md

@@ -0,0 +1,25 @@
+# User Replies
+
+## One-liner Pitch
+
+我会先帮你完成注册并拿到第一个 agent 参数，然后交给 `grix-admin` 完成本地配置。
+
+## Short Intro
+
+`grix-register` 只负责账号和云端参数准备，不改本地配置；本地配置由 `grix-admin` 接手。
+
+## Ready Reply
+
+账号和首个 agent 参数已经准备好，接下来我会把参数交给 `grix-admin` 做本地配置。
+
+## Main Ready, Admin Pending Reply
+
+`grix-register` 阶段已完成，我现在只做参数移交，后续本地配置请由 `grix-admin` 继续。
+
+## Configured Now Reply
+
+参数已交接给 `grix-admin`，接下来由它完成本地配置。
+
+## Needs Setup Reply
+
+当前仍在 `grix-register` 阶段，我会继续完成注册并拿到第一个 agent 参数。

package/skills/grix-register/scripts/grix_auth.py

@@ -0,0 +1,453 @@
+#!/usr/bin/env python3
+import argparse
+import base64
+import json
+import os
+import sys
+import tempfile
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+
+
+DEFAULT_BASE_URL = "https://grix.dhf.pub"
+DEFAULT_TIMEOUT_SECONDS = 15
+DEFAULT_PORTAL_URL = "https://grix.dhf.pub/"
+
+
+class GrixAuthError(RuntimeError):
+    def __init__(self, message, status=0, code=-1, payload=None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.payload = payload
+
+
+def normalize_base_url(raw_base_url: str) -> str:
+    base = (raw_base_url or "").strip() or DEFAULT_BASE_URL
+    parsed = urllib.parse.urlparse(base)
+    if not parsed.scheme or not parsed.netloc:
+        raise ValueError(f"Invalid base URL: {base}")
+
+    path = parsed.path.rstrip("/")
+    if not path:
+        path = "/v1"
+    elif not path.endswith("/v1"):
+        path = f"{path}/v1"
+
+    normalized = parsed._replace(path=path, params="", query="", fragment="")
+    return urllib.parse.urlunparse(normalized).rstrip("/")
+
+
+def request_json(method: str, path: str, base_url: str, body=None, headers=None):
+    api_base_url = normalize_base_url(base_url)
+    url = f"{api_base_url}{path if path.startswith('/') else '/' + path}"
+    data = None
+    final_headers = dict(headers or {})
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        final_headers["Content-Type"] = "application/json"
+
+    req = urllib.request.Request(url=url, data=data, headers=final_headers, method=method)
+    try:
+        with urllib.request.urlopen(req, timeout=DEFAULT_TIMEOUT_SECONDS) as resp:
+            status = getattr(resp, "status", 200)
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        status = exc.code
+        raw = exc.read().decode("utf-8", errors="replace")
+    except urllib.error.URLError as exc:
+        raise GrixAuthError(f"network error: {exc.reason}") from exc
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise GrixAuthError(f"invalid json response: {raw[:256]}", status=status) from exc
+
+    code = int(payload.get("code", -1))
+    msg = str(payload.get("msg", "")).strip() or "unknown error"
+    if status >= 400 or code != 0:
+        raise GrixAuthError(msg, status=status, code=code, payload=payload)
+
+    return {
+        "api_base_url": api_base_url,
+        "status": status,
+        "data": payload.get("data"),
+        "payload": payload,
+    }
+
+
+def maybe_write_captcha_image(b64s: str):
+    text = (b64s or "").strip()
+    if not text.startswith("data:image/"):
+        return ""
+
+    marker = ";base64,"
+    idx = text.find(marker)
+    if idx < 0:
+        return ""
+
+    encoded = text[idx + len(marker) :]
+    try:
+        content = base64.b64decode(encoded)
+    except Exception:
+        return ""
+
+    fd, path = tempfile.mkstemp(prefix="grix-captcha-", suffix=".png")
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(content)
+    except Exception:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+        return ""
+    return path
+
+
+def print_json(payload):
+    json.dump(payload, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+
+
+def build_auth_result(action: str, result: dict):
+    data = result.get("data") or {}
+    user = data.get("user") or {}
+    return {
+        "ok": True,
+        "action": action,
+        "api_base_url": result["api_base_url"],
+        "access_token": data.get("access_token", ""),
+        "refresh_token": data.get("refresh_token", ""),
+        "expires_in": data.get("expires_in", 0),
+        "user_id": user.get("id", ""),
+        "portal_url": DEFAULT_PORTAL_URL,
+        "data": data,
+    }
+
+
+def build_agent_result(action: str, result: dict):
+    data = result.get("data") or {}
+    agent_id = str(data.get("id", "")).strip()
+    api_endpoint = str(data.get("api_endpoint", "")).strip()
+    api_key = str(data.get("api_key", "")).strip()
+
+    return {
+        "ok": True,
+        "action": action,
+        "api_base_url": result["api_base_url"],
+        "agent_id": agent_id,
+        "agent_name": data.get("agent_name", ""),
+        "provider_type": data.get("provider_type", 0),
+        "api_endpoint": api_endpoint,
+        "api_key": api_key,
+        "api_key_hint": data.get("api_key_hint", ""),
+        "session_id": data.get("session_id", ""),
+        "handoff": {
+            "target_skill": "grix-admin",
+            "payload": {
+                "agent_id": agent_id,
+                "agent_name": data.get("agent_name", ""),
+                "api_endpoint": api_endpoint,
+                "api_key": api_key,
+            },
+        },
+        "data": data,
+    }
+
+
+def login_with_credentials(base_url: str, account: str, password: str, device_id: str, platform: str):
+    result = request_json(
+        "POST",
+        "/auth/login",
+        base_url,
+        body={
+            "account": account,
+            "password": password,
+            "device_id": device_id,
+            "platform": platform,
+        },
+    )
+    return build_auth_result("login", result)
+
+
+def create_api_agent(base_url: str, access_token: str, agent_name: str, avatar_url: str):
+    request_body = {
+        "agent_name": agent_name.strip(),
+        "provider_type": 3,
+        "is_main": True,
+    }
+    normalized_avatar_url = (avatar_url or "").strip()
+    if normalized_avatar_url:
+        request_body["avatar_url"] = normalized_avatar_url
+
+    result = request_json(
+        "POST",
+        "/agents/create",
+        base_url,
+        body=request_body,
+        headers={
+            "Authorization": f"Bearer {access_token.strip()}",
+        },
+    )
+    return build_agent_result("create-api-agent", result)
+
+
+def list_agents(base_url: str, access_token: str):
+    result = request_json(
+        "GET",
+        "/agents/list",
+        base_url,
+        headers={
+            "Authorization": f"Bearer {access_token.strip()}",
+        },
+    )
+    data = result.get("data") or {}
+    items = data.get("list") or []
+    if not isinstance(items, list):
+        items = []
+    return items
+
+
+def rotate_api_agent_key(base_url: str, access_token: str, agent_id: str):
+    result = request_json(
+        "POST",
+        f"/agents/{str(agent_id).strip()}/api/key/rotate",
+        base_url,
+        body={},
+        headers={
+            "Authorization": f"Bearer {access_token.strip()}",
+        },
+    )
+    return build_agent_result("rotate-api-agent-key", result)
+
+
+def find_existing_api_agent(agents, agent_name: str):
+    normalized_name = (agent_name or "").strip()
+    if not normalized_name:
+        return None
+
+    for item in agents:
+        if not isinstance(item, dict):
+            continue
+        if str(item.get("agent_name", "")).strip() != normalized_name:
+            continue
+        if int(item.get("provider_type", 0) or 0) != 3:
+            continue
+        if int(item.get("status", 0) or 0) == 3:
+            continue
+        return item
+    return None
+
+
+def create_or_reuse_api_agent(
+    base_url: str,
+    access_token: str,
+    agent_name: str,
+    avatar_url: str,
+    prefer_existing: bool,
+    rotate_on_reuse: bool,
+):
+    if prefer_existing:
+        agents = list_agents(base_url, access_token)
+        existing = find_existing_api_agent(agents, agent_name)
+        if existing is not None:
+            if not rotate_on_reuse:
+                raise GrixAuthError(
+                    "existing provider_type=3 agent found but rotate-on-reuse is disabled; cannot obtain api_key safely",
+                    payload={"existing_agent": existing},
+                )
+            rotated = rotate_api_agent_key(base_url, access_token, str(existing.get("id", "")).strip())
+            rotated["source"] = "reused_existing_agent_with_rotated_key"
+            rotated["existing_agent"] = existing
+            return rotated
+
+    created = create_api_agent(base_url, access_token, agent_name, avatar_url)
+    created["source"] = "created_new_agent"
+    return created
+
+
+def default_device_id(platform: str) -> str:
+    normalized_platform = (platform or "").strip() or "web"
+    return f"{normalized_platform}_{uuid.uuid4()}"
+
+
+def handle_fetch_captcha(args):
+    result = request_json("GET", "/auth/captcha", args.base_url)
+    data = result.get("data") or {}
+    image_path = maybe_write_captcha_image(str(data.get("b64s", "")))
+    payload = {
+        "ok": True,
+        "action": "fetch-captcha",
+        "api_base_url": result["api_base_url"],
+        "captcha_id": data.get("captcha_id", ""),
+        "b64s": data.get("b64s", ""),
+    }
+    if image_path:
+        payload["captcha_image_path"] = image_path
+    print_json(payload)
+
+
+def handle_send_email_code(args):
+    scene = args.scene.strip()
+    payload = {
+        "email": args.email.strip(),
+        "scene": scene,
+    }
+
+    captcha_id = (args.captcha_id or "").strip()
+    captcha_value = (args.captcha_value or "").strip()
+    if scene in {"reset", "change_password"}:
+        if not captcha_id or not captcha_value:
+            raise GrixAuthError("captcha_id and captcha_value are required for reset/change_password")
+    if captcha_id:
+        payload["captcha_id"] = captcha_id
+    if captcha_value:
+        payload["captcha_value"] = captcha_value
+
+    result = request_json(
+        "POST",
+        "/auth/send-code",
+        args.base_url,
+        body=payload,
+    )
+    print_json(
+        {
+            "ok": True,
+            "action": "send-email-code",
+            "api_base_url": result["api_base_url"],
+            "data": result.get("data"),
+        }
+    )
+
+
+def handle_register(args):
+    platform = (args.platform or "").strip() or "web"
+    device_id = (args.device_id or "").strip() or default_device_id(platform)
+    result = request_json(
+        "POST",
+        "/auth/register",
+        args.base_url,
+        body={
+            "email": args.email.strip(),
+            "password": args.password.strip(),
+            "email_code": args.email_code.strip(),
+            "device_id": device_id,
+            "platform": platform,
+        },
+    )
+    print_json(build_auth_result("register", result))
+
+
+def handle_login(args):
+    account = (args.email or args.account or "").strip()
+    if not account:
+        raise GrixAuthError("either --email or --account is required")
+
+    platform = (args.platform or "").strip() or "web"
+    device_id = (args.device_id or "").strip() or default_device_id(platform)
+    print_json(
+        login_with_credentials(
+            args.base_url,
+            account,
+            args.password.strip(),
+            device_id,
+            platform,
+        )
+    )
+
+
+def handle_create_api_agent(args):
+    print_json(
+        create_or_reuse_api_agent(
+            args.base_url,
+            args.access_token.strip(),
+            args.agent_name.strip(),
+            args.avatar_url,
+            not bool(args.no_reuse_existing_agent),
+            not bool(args.no_rotate_key_on_reuse),
+        )
+    )
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description="Grix public auth API helper")
+    parser.add_argument("--base-url", default=DEFAULT_BASE_URL, help="Grix web base URL")
+
+    subparsers = parser.add_subparsers(dest="action", required=True)
+
+    fetch_captcha = subparsers.add_parser("fetch-captcha", help="Fetch captcha image")
+    fetch_captcha.set_defaults(handler=handle_fetch_captcha)
+
+    send_email_code = subparsers.add_parser("send-email-code", help="Send email verification code")
+    send_email_code.add_argument("--email", required=True)
+    send_email_code.add_argument("--scene", required=True, choices=["register", "reset", "change_password"])
+    send_email_code.add_argument("--captcha-id", default="")
+    send_email_code.add_argument("--captcha-value", default="")
+    send_email_code.set_defaults(handler=handle_send_email_code)
+
+    register = subparsers.add_parser("register", help="Register by email verification code")
+    register.add_argument("--email", required=True)
+    register.add_argument("--password", required=True)
+    register.add_argument("--email-code", required=True)
+    register.add_argument("--device-id", default="")
+    register.add_argument("--platform", default="web")
+    register.set_defaults(handler=handle_register)
+
+    login = subparsers.add_parser("login", help="Login and obtain tokens")
+    login_identity = login.add_mutually_exclusive_group(required=True)
+    login_identity.add_argument("--account")
+    login_identity.add_argument("--email")
+    login.add_argument("--password", required=True)
+    login.add_argument("--device-id", default="")
+    login.add_argument("--platform", default="web")
+    login.set_defaults(handler=handle_login)
+
+    create_api_agent_parser = subparsers.add_parser(
+        "create-api-agent",
+        help="Create a provider_type=3 API agent with a user access token",
+    )
+    create_api_agent_parser.add_argument("--access-token", required=True)
+    create_api_agent_parser.add_argument("--agent-name", required=True)
+    create_api_agent_parser.add_argument("--avatar-url", default="")
+    create_api_agent_parser.add_argument("--no-reuse-existing-agent", action="store_true")
+    create_api_agent_parser.add_argument("--no-rotate-key-on-reuse", action="store_true")
+    create_api_agent_parser.set_defaults(handler=handle_create_api_agent)
+
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        args.handler(args)
+    except GrixAuthError as exc:
+        print_json(
+            {
+                "ok": False,
+                "action": args.action,
+                "status": exc.status,
+                "code": exc.code,
+                "error": str(exc),
+                "payload": exc.payload,
+            }
+        )
+        raise SystemExit(1)
+    except Exception as exc:
+        print_json(
+            {
+                "ok": False,
+                "action": args.action,
+                "status": 0,
+                "code": -1,
+                "error": str(exc),
+            }
+        )
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/grix-agent-admin/SKILL.md

@@ -1,85 +0,0 @@
----
-name: grix-agent-admin
-description: 通过 Grix Agent API 协议创建 `provider_type=3` 的 API agent，并直接完成本地 OpenClaw agent 与 Grix 渠道绑定配置（默认直接应用并返回结果）。
----
-
-# Grix Agent Admin
-
-Create a remote `provider_type=3` API agent, then complete local OpenClaw agent + grix channel binding in one flow.
-
-## Security + Auth Path
-
-1. This skill does **not** ask the user for website account/password.
-2. Remote create action uses local `channels.grix` credentials and `Authorization: Bearer <agent_api_key>`.
-3. Local OpenClaw config is handled by `scripts/grix_agent_bind.py`.
-
-## Required Input
-
-1. `agentName` (required): regex `^[a-z][a-z0-9-]{2,31}$`
-2. `describeMessageTool` (required): must contain non-empty `actions`
-3. `accountId` (optional)
-4. `avatarUrl` (optional)
-
-## Full Workflow
-
-### A. Create Remote API Agent
-
-1. Validate `agentName` and `describeMessageTool`.
-2. Call `grix_agent_admin` once.
-3. Read result fields: `id`, `agent_name`, `api_endpoint`, `api_key`, `api_key_hint`.
-
-### B. Apply Local OpenClaw Binding Directly
-
-Run with `--apply` directly:
-
-```bash
-scripts/grix_agent_bind.py configure-local-openclaw \
-  --agent-name <agent_name> \
-  --agent-id <agent_id> \
-  --api-endpoint '<api_endpoint>' \
-  --api-key '<api_key>' \
-  --apply
-```
-
-This applies:
-
-1. upsert `agents.list` for `<agent_name>`
-2. upsert `channels.grix.accounts.<agent_name>`
-3. upsert `bindings` route to `channel=grix`, `accountId=<agent_name>`
-4. ensure required tools (`message`, `grix_group`, `grix_agent_admin`)
-5. create workspace defaults under `~/.openclaw/workspace-<agent_name>/`
-6. run `openclaw gateway restart`
-
-### C. Optional Verification
-
-If you need explicit post-check state, run:
-
-```bash
-scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>
-```
-
-## Guardrails
-
-1. Never ask user for website account/password.
-2. Treat remote create as non-idempotent; do not auto-retry without confirmation.
-3. Keep full `api_key` one-time only; do not repeatedly echo it.
-4. Do not claim success before apply command returns success.
-
-## Error Handling Rules
-
-1. invalid name: ask user for a valid English lowercase name.
-2. `403/20011`: ask owner to grant `agent.api.create` scope.
-3. `401/10001`: verify local `agent_api_key` / grix account config.
-4. `409/20002`: ask for another agent name.
-5. local apply failed: return concrete failed command/result and stop.
-
-## Response Style
-
-1. Report two stages separately: remote create status + local binding status.
-2. Include created `agent_id`, `agent_name`, `api_endpoint`, `api_key_hint`.
-3. Clearly state local config has been applied (or failed with concrete reason).
-
-## References
-
-1. Load [references/api-contract.md](references/api-contract.md).
-2. Use [scripts/grix_agent_bind.py](scripts/grix_agent_bind.py) for local binding apply.

package/skills/grix-agent-admin/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Grix Agent Admin"
-  short_description: "Create Grix API agents and finish local OpenClaw binding."
-  default_prompt: "Use this skill when users ask to create a new Grix API agent and finish OpenClaw binding. Never ask for website account/password. Validate `agentName` and require `describeMessageTool` (`actions` must be non-empty), then call `grix_agent_admin` once. After successful create, directly run `scripts/grix_agent_bind.py configure-local-openclaw ... --apply` and return final local binding result (success or exact failure reason)."

package/skills/grix-group-governance/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Grix Group Governance"
-  short_description: "Use the typed grix_group tool for Grix group operations."
-  default_prompt: "Use this skill when users ask to create, inspect, update, or dissolve Grix groups. Validate parameters, call grix_group exactly once per action, and return clear remediation for scope/auth/parameter failures."

package/skills/grix-query/agents/openai.yaml

@@ -1,4 +0,0 @@
-version: 1
-agent:
-  name: grix-query
-  default_prompt: "Use this skill when users ask to find Grix contacts, locate sessions, or inspect a known session's message history. Validate required parameters, call grix_query exactly once per action, and do not fabricate a sessionId."