@dhf-openclaw/grix 0.4.8 → 0.4.10

package/README.md

@@ -1,38 +1,42 @@
-# OpenClaw Grix Channel Plugin
+# OpenClaw Grix Unified Plugin
 
-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.
+This plugin connects OpenClaw to [https://grix.dhf.pub/](https://grix.dhf.pub/) and provides a single, unified integration for:
+
+- Grix channel transport (WebSocket Agent API)
+- native message actions (`unsend` / `delete`)
+- typed Grix admin tools
+- operator CLI commands
+- bundled Grix workflow skills
 
 Compatibility:
 
 - Requires `OpenClaw >= 2026.3.13`
 
-Its runtime remains focused on channel responsibilities:
-
-- 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`
-
-The npm package also bundles OpenClaw skills for first-time setup and native channel actions, so users can install the plugin and complete Grix onboarding directly in conversation.
-
-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 the bundled onboarding skill
-- 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`
+## Included Capability
+
+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
 
-Before install, confirm your local OpenClaw version is greater than or equal to `2026.3.13`.
-
-### Base Channel Transport
-
 ```bash
 openclaw plugins install @dhf-openclaw/grix
 openclaw plugins enable grix
@@ -41,37 +45,31 @@ openclaw gateway restart
 
 ### Local Source Checkout
 
-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:
+If you load from a local checkout:
 
 ```bash
 npm install
-```
-
-Then point OpenClaw at the tracked local entry file:
-
-```bash
 openclaw plugins install ./grix.ts
 ```
 
-### Full Grix Capability
+## Required OpenClaw Config
 
-For native group-management capability inside OpenClaw, also install the admin plugin and enable the required tools:
+### Channel Config (`channels.grix`)
 
-```bash
-openclaw plugins install @dhf-openclaw/grix-admin
-openclaw plugins enable grix-admin
-openclaw gateway restart
+```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>"
+    }
+  }
+}
 ```
 
-Recommended order:
-
-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
-
-If you need the detailed admin-side requirements, see the companion Grix admin plugin README.
+### Tool Exposure Config
 
 ```json
 {
@@ -79,6 +77,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,44 +88,7 @@ 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:
-
-- `grix-auth-access`: inspect current readiness, follow the protocol-based main-agent path, create or reuse `provider_type=3` API agents when an access token is already available, install or enable `@dhf-openclaw/grix-admin`, and configure the main `channels.grix` path plus required tools
-- `egg-install`: handle Shrimp Pond egg install chats, confirm targets with the user in the current private conversation, execute persona.zip or skill.zip installation with正规步骤, and report progress or failures in normal dialogue
-- `message-send`: send current-session or cross-session Grix messages
-- `message-unsend`: unsend previously sent Grix messages
-
-You can confirm the bundled skill is visible with:
-
-```bash
-openclaw skills list
-openclaw skills info grix-auth-access
-```
-
-If the local main channel is already ready, `grix-auth-access` tells the user to log in to [https://grix.dhf.pub/](https://grix.dhf.pub/) directly. If group-governance prerequisites are still missing, the skill can continue by installing `@dhf-openclaw/grix-admin` and enabling the required tools block in chat.
-
-## Configure
-
-### `openclaw onboard`
-
-Choose `Grix` in channel setup and enter:
-
-- `wsUrl`
-- `agentId`
-- `apiKey`
-
-### `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
+Full example:
 
 ```json
 {
@@ -142,6 +104,7 @@ openclaw channels add \
     "profile": "coding",
     "alsoAllow": [
       "message",
+      "grix_query",
       "grix_group",
       "grix_agent_admin"
     ],
@@ -152,18 +115,71 @@ openclaw channels add \
 }
 ```
 
-The `channels.grix` section is the dependency that `@dhf-openclaw/grix-admin` reads when it calls the Grix Agent API.
+After any config change:
+
+```bash
+openclaw gateway restart
+```
+
+## 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
+
+```bash
+openclaw grix doctor
+```
+
+### Create API agent
+
+```bash
+openclaw grix create-agent \
+  --agent-name ops-assistant \
+  --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
+
+`--describe-message-tool` is required and must follow OpenClaw `describeMessageTool` discovery structure.
 
 ## 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": {
@@ -177,14 +193,14 @@ Add the Grix sender ids that are allowed to approve:
 }
 ```
 
-If you use a named Grix account, configure approvers under that account:
+If using named accounts:
 
 ```json
 {
   "channels": {
     "grix": {
       "accounts": {
-        "xiami": {
+        "ops": {
           "execApprovals": {
             "enabled": true,
             "approvers": ["<GRIX_SENDER_ID>"]
@@ -198,8 +214,6 @@ If you use a named Grix account, configure approvers under that account:
 
 ### 2. Enable OpenClaw exec approvals
 
-Minimal OpenClaw config:
-
 ```json
 {
   "tools": {
@@ -226,17 +240,13 @@ Minimal OpenClaw config:
 }
 ```
 
-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
+Mode choices:
 
-If needed, you can also use OpenClaw's upstream `approvals.exec` fields such as `agentFilter`, `sessionFilter`, and `targets`.
+- `session`: send approval prompt to current Grix chat
+- `targets`: send approval prompt to configured `approvals.exec.targets`
+- `both`: send to both
 
-### 3. Restart the gateway
-
-After changing any approval-related config:
+### 3. Restart
 
 ```bash
 openclaw gateway restart
@@ -244,73 +254,32 @@ openclaw gateway restart
 
 ### 4. Approve in chat
 
-Usage flow:
+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`.
+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 the `exec` request based on that decision.
+4. OpenClaw continues or denies execution.
 
 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
+- approvers must be Grix sender IDs, not OpenClaw agent IDs
+- configure approvers under the serving account
+- approval requests and results are posted in chat
 
-### 5. Quick checks
+## Verification
 
 ```bash
 openclaw plugins info grix --json
-openclaw config get approvals.exec --json
-openclaw config get channels.grix --json
+openclaw skills list
+openclaw grix doctor
 ```
 
-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`
-
-## Bundled Onboarding Skill
-
-Grix fully adapts the OpenClaw communication protocol, so OpenClaw interaction and Grix agent communication are directly connected. The bundled `grix-auth-access` skill is intended to explain that model to the user and complete the onboarding path:
-
-1. inspect whether the local OpenClaw main agent is already configured
-2. if the main channel is already configured, tell the user they can log in to [https://grix.dhf.pub/](https://grix.dhf.pub/) immediately
-3. otherwise continue with the protocol-based agent setup path
-4. create or reuse a `provider_type=3` API agent
-5. install or enable `@dhf-openclaw/grix-admin` when group-governance capability is requested
-6. configure the OpenClaw main `channels.grix` entry and required tools block
-
-This gives users a direct “install plugin, enable it, then finish setup in conversation” path. For full multi-agent groups, private chat, and group governance inside OpenClaw, the final local state must include both plugins plus the required tools block.
-
-## Environment Variables
+Expected:
 
-- `GRIX_WS_URL`
-- `GRIX_AGENT_ID`
-- `GRIX_API_KEY`
+- 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