@dhf-openclaw/grix 0.4.9 → 0.4.11

package/README.md

@@ -1,77 +1,46 @@
-# OpenClaw Grix Channel Plugin
+# OpenClaw Grix 插件
 
-This plugin connects OpenClaw to [https://grix.dhf.pub/](https://grix.dhf.pub/) so OpenClaw can be managed on that website, with mobile PWA page support.
+把 OpenClaw 接到 Grix（`grix.dhf.pub`）的统一插件，包含：
 
-Compatibility:
+- Grix Channel（收发消息、流式回复、`unsend`、`delete`）
+- 管理工具：`grix_query`、`grix_group`、`grix_agent_admin`
+- 运维命令：`openclaw grix doctor`、`openclaw grix create-agent`
+- 内置技能包（`skills/`）
 
-- Requires `OpenClaw >= 2026.3.13`
+## 兼容性
 
-Its runtime remains focused on channel responsibilities:
+- `OpenClaw >= 2026.3.23-1`
 
-- connect to Grix over the Agent API WebSocket
-- receive inbound messages
-- send replies, media, and streaming chunks
-- support native channel actions such as `unsend` / `delete`
+## 5 分钟安装（推荐）
 
-The npm package also bundles OpenClaw skills for channel helpers and native channel actions.
-
-For full group-governance and API-agent admin capability, OpenClaw also needs the separate typed admin plugin:
-
-- `@dhf-openclaw/grix-admin`
-
-If you are reading the admin plugin documentation first, also read the companion Grix admin plugin README.
-
-## Which Package Do I Need?
-
-- Install only `@dhf-openclaw/grix` when you only need Grix channel transport and bundled helper skills
-- Install both `@dhf-openclaw/grix` and `@dhf-openclaw/grix-admin` when you want OpenClaw agents to use typed group governance or API-agent admin tools
-- Never install only `@dhf-openclaw/grix-admin` without configuring `@dhf-openclaw/grix` first, because the admin plugin reads credentials from `channels.grix`
-
-## Install
-
-Before install, confirm your local OpenClaw version is greater than or equal to `2026.3.13`.
-
-### Base Channel Transport
+### 1) 安装并启用插件
 
 ```bash
 openclaw plugins install @dhf-openclaw/grix
 openclaw plugins enable grix
-openclaw gateway restart
 ```
 
-### Local Source Checkout
+### 2) 绑定 Grix Channel
 
-If you load this plugin directly from a local checkout instead of the published npm package, install repo dependencies first so `openclaw/plugin-sdk` can resolve from this workspace:
+用你已有的 Grix API agent 信息执行：
 
 ```bash
-npm install
-```
-
-Then point OpenClaw at the tracked local entry file:
-
-```bash
-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>"
 ```
 
-### Full Grix Capability
-
-For native group-management capability inside OpenClaw, also install the admin plugin and enable the required tools:
-
-```bash
-openclaw plugins install @dhf-openclaw/grix-admin
-openclaw plugins enable grix-admin
-openclaw gateway restart
-```
+说明：
 
-Recommended order:
+- `--http-url` 可以带 `agent_id`，也可以不带。不带时会自动按 `--user-id` 补上。
+- `--name` 是本地账户名，可自定义（如 `ops`、`prod`）。
 
-1. Install and configure `@dhf-openclaw/grix`
-2. Confirm `channels.grix` is healthy
-3. Install and enable `@dhf-openclaw/grix-admin`
-4. Enable the required `tools` block
-5. Restart the OpenClaw gateway
+### 3) 开放工具权限
 
-If you need the detailed admin-side requirements, see the companion Grix admin plugin README.
+在 OpenClaw 配置里确保有：
 
 ```json
 {
@@ -79,6 +48,7 @@ If you need the detailed admin-side requirements, see the companion Grix admin p
     "profile": "coding",
     "alsoAllow": [
       "message",
+      "grix_query",
       "grix_group",
       "grix_agent_admin"
     ],
@@ -89,41 +59,31 @@ If you need the detailed admin-side requirements, see the companion Grix admin p
 }
 ```
 
-After install, OpenClaw can surface these bundled skills from this plugin:
+### 4) 重启网关
 
-- `message-send`: send current-session or cross-session Grix messages
-- `message-unsend`: unsend previously sent Grix messages
-
-`egg-install` is bundled in `@dhf-openclaw/grix-admin` so install the admin plugin when you need Shrimp Pond install workflow.
+```bash
+openclaw gateway restart
+```
 
-You can confirm the bundled skill is visible with:
+### 5) 验证安装结果
 
 ```bash
+openclaw plugins info grix --json
+openclaw grix doctor
 openclaw skills list
 ```
 
-## Configure
+预期：
 
-### `openclaw onboard`
+- `grix` 插件已启用
+- `doctor` 能看到可用账户
+- `skills list` 能看到本插件内置技能
 
-Choose `Grix` in channel setup and enter:
+## 配置参数说明（完整）
 
-- `wsUrl`
-- `agentId`
-- `apiKey`
+`channels.grix` 支持“单账户”或“多账户（accounts）”两种写法。
 
-### `openclaw channels add`
-
-```bash
-openclaw channels add \
-  --channel grix \
-  --name grix-main \
-  --http-url 'wss://grix.dhf.pub/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>' \
-  --user-id '<YOUR_AGENT_ID>' \
-  --token '<YOUR_API_KEY>'
-```
-
-### Direct config
+### 最小可用配置（单账户）
 
 ```json
 {
@@ -134,68 +94,126 @@ openclaw channels add \
       "agentId": "<YOUR_AGENT_ID>",
       "apiKey": "<YOUR_API_KEY>"
     }
-  },
-  "tools": {
-    "profile": "coding",
-    "alsoAllow": [
-      "message",
-      "grix_group",
-      "grix_agent_admin"
-    ],
-    "sessions": {
-      "visibility": "agent"
-    }
   }
 }
 ```
 
-The `channels.grix` section is the dependency that `@dhf-openclaw/grix-admin` reads when it calls the Grix Agent API.
-
-## Exec Approvals
-
-Grix can approve OpenClaw host `exec` requests in chat.
-
-`exec` approvals only require `@dhf-openclaw/grix`. They do not require `@dhf-openclaw/grix-admin`.
-
-### 1. Configure Grix approvers
-
-Add the Grix sender ids that are allowed to approve:
+### 多账户配置示例
 
 ```json
 {
   "channels": {
     "grix": {
-      "execApprovals": {
-        "enabled": true,
-        "approvers": ["<GRIX_SENDER_ID>"]
+      "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>"
+        }
       }
     }
   }
 }
 ```
 
-If you use a named Grix account, configure approvers under that account:
+### 字段说明
+
+| 字段 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `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
+```
+
+创建 API agent：
+
+```bash
+openclaw grix create-agent \
+  --agent-name ops-assistant \
+  --describe-message-tool '{"actions":["unsend","delete"]}'
+```
+
+参数说明：
+
+- `--agent-name`：必填，小写字母开头，只允许小写字母、数字、`-`，长度 3-32。
+- `--describe-message-tool`：必填，JSON 对象，至少包含 `actions` 数组。
+- `--account-id`：可选，指定用哪个本地 Grix 账户发起创建。
+- `--avatar-url`：可选，给新 agent 设置头像地址。
+
+命令输出里会给出一次性 `api_key` 和下一步绑定命令模板。
+
+## 聊天内 Exec 审批（可选）
+
+先在 Grix 账户里配置审批人：
 
 ```json
 {
   "channels": {
     "grix": {
-      "accounts": {
-        "xiami": {
-          "execApprovals": {
-            "enabled": true,
-            "approvers": ["<GRIX_SENDER_ID>"]
-          }
-        }
+      "execApprovals": {
+        "enabled": true,
+        "approvers": ["<GRIX_SENDER_ID>"]
       }
     }
   }
 }
 ```
 
-### 2. Enable OpenClaw exec approvals
-
-Minimal OpenClaw config:
+再开启 OpenClaw 的 exec 审批：
 
 ```json
 {
@@ -211,90 +229,18 @@ Minimal OpenClaw config:
       "enabled": true,
       "mode": "session"
     }
-  },
-  "channels": {
-    "grix": {
-      "execApprovals": {
-        "enabled": true,
-        "approvers": ["<GRIX_SENDER_ID>"]
-      }
-    }
   }
 }
 ```
 
-Mode selection:
-
-- `session`: send the approval prompt back to the current Grix chat
-- `targets`: send the approval prompt to the explicit targets configured in `approvals.exec.targets`
-- `both`: send to the current chat and to explicit targets
-
-If needed, you can also use OpenClaw's upstream `approvals.exec` fields such as `agentFilter`, `sessionFilter`, and `targets`.
+`mode` 说明：
 
-### 3. Restart the gateway
+- `session`：发到当前会话
+- `targets`：发到 `approvals.exec.targets`
+- `both`：两边都发
 
-After changing any approval-related config:
+配置改完后重启：
 
 ```bash
 openclaw gateway restart
 ```
-
-### 4. Approve in chat
-
-Usage flow:
-
-1. Ask OpenClaw to run an `exec` command that requires approval.
-2. OpenClaw sends the approval prompt to Grix according to `approvals.exec.mode`.
-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 the `exec` request based on that decision.
-
-Notes:
-
-- `approvers` must be Grix sender ids, not OpenClaw agent ids
-- put approvers under the Grix account that is actually serving the session
-- approval requests and approval results are shown in chat
-- some OpenClaw lifecycle notices may still appear as normal text
-
-### 5. Quick checks
-
-```bash
-openclaw plugins info grix --json
-openclaw config get approvals.exec --json
-openclaw config get channels.grix --json
-```
-
-Check that:
-
-- `plugins info grix` reports `status = "loaded"`
-- `approvals.exec.enabled = true`
-- `approvals.exec.mode` matches your intended delivery path
-- the active Grix account has `execApprovals.enabled = true`
-- the active Grix account has at least one sender id in `execApprovals.approvers`
-
-Troubleshooting:
-
-- if no approval card appears in the current chat, first confirm `tools.exec.ask = "always"` and `approvals.exec.mode = "session"`
-- if you are forwarding to explicit Grix targets, confirm `approvals.exec.targets` points to the correct `channel = "grix"` target
-- if the chat shows approval text but approvers cannot operate it, check that `approvers` contains the human Grix sender id
-- if `openclaw gateway restart` fails config validation, remove invalid keys under `approvals.exec` and keep approver ids only under `channels.grix.*.execApprovals`
-
-For an end-to-end verification checklist, see:
-
-- [docs/openclaw_exec_approval_e2e.md](../../docs/openclaw_exec_approval_e2e.md)
-
-For multi-account setups, put `execApprovals` under `channels.grix.accounts.<accountId>`.
-
-## Native Channel Actions
-
-The channel plugin exposes only channel-native message actions:
-
-- `unsend`
-- `delete`
-
-## Environment Variables
-
-- `GRIX_WS_URL`
-- `GRIX_AGENT_ID`
-- `GRIX_API_KEY`