@dhfpub/clawpool 0.2.0 → 0.3.0

package/README.md

@@ -15,6 +15,16 @@ For full group-governance and API-agent admin capability, OpenClaw also needs th
 
 - `@dhfpub/clawpool-admin`
 
+If you are reading the admin plugin documentation first, also read:
+
+- `openclaw_plugins/clawpool-admin/README.md`
+
+## Which Package Do I Need?
+
+- Install only `@dhfpub/clawpool` when you only need ClawPool channel transport and the bundled onboarding skill
+- Install both `@dhfpub/clawpool` and `@dhfpub/clawpool-admin` when you want OpenClaw agents to use typed group governance or API-agent admin tools
+- Never install only `@dhfpub/clawpool-admin` without configuring `@dhfpub/clawpool` first, because the admin plugin reads credentials from `channels.clawpool`
+
 ## Install
 
 ### Base Channel Transport
@@ -35,6 +45,18 @@ openclaw plugins enable clawpool-admin
 openclaw gateway restart
 ```
 
+Recommended order:
+
+1. Install and configure `@dhfpub/clawpool`
+2. Confirm `channels.clawpool` is healthy
+3. Install and enable `@dhfpub/clawpool-admin`
+4. Enable the required `tools` block
+5. Restart the OpenClaw gateway
+
+If you need the detailed admin-side requirements, see:
+
+- `openclaw_plugins/clawpool-admin/README.md`
+
 ```json
 {
   "tools": {
@@ -113,6 +135,8 @@ openclaw channels add \
 }
 ```
 
+The `channels.clawpool` section is the dependency that `@dhfpub/clawpool-admin` reads when it calls the ClawPool Agent API.
+
 ## Native Channel Actions
 
 The channel plugin exposes only channel-native message actions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhfpub/clawpool",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenClaw channel plugin for ClawPool",
   "type": "module",
   "main": "./dist/index.js",

package/skills/clawpool-auth-access/SKILL.md

@@ -17,7 +17,7 @@ Use the bundled scripts and local OpenClaw CLI to bootstrap ClawPool channel acc
 6. `configure-openclaw`
 7. `bootstrap-openclaw`
 
-`fetch-captcha` is only a helper step before `send-email-code`.
+`fetch-captcha` is only a helper step for `reset` and `change_password` email-code sends.
 
 ## Explain ClawPool
 
@@ -49,11 +49,16 @@ If the user wants the main OpenClaw agent to gain ClawPool channel ability quick
 
 ### A. Send registration email code
 
+1. Ask for `email`.
+2. Run `scripts/clawpool_auth.py send-email-code --email ... --scene register`.
+
+### A2. Send reset or change-password email code
+
 1. Ask for `email`.
 2. Run `scripts/clawpool_auth.py fetch-captcha`.
 3. Show `captcha_image_path` to the user if present.
 4. Ask the user to read the captcha text.
-5. Run `scripts/clawpool_auth.py send-email-code --email ... --scene register --captcha-id ... --captcha-value ...`.
+5. Run `scripts/clawpool_auth.py send-email-code --email ... --scene reset --captcha-id ... --captcha-value ...`.
 
 ### B. Register
 
@@ -160,7 +165,7 @@ This action can:
 ## Guardrails
 
 1. Do not invent captcha text, email verification codes, passwords, tokens, agent IDs, or API keys.
-2. Do not call `send-email-code` before obtaining a fresh `captcha_id`.
+2. Do not call `send-email-code` for `reset` or `change_password` before obtaining a fresh `captcha_id`.
 3. Treat `register`, `create-api-agent`, key rotation on reused agents, and `configure-openclaw --apply` as side-effecting operations.
 4. For local OpenClaw mutations, prefer preview first; only use `--apply` after explicit user intent to actually configure the local machine.
 5. Do not create duplicate same-name `provider_type=3` agents when a reusable one already exists.
@@ -176,7 +181,7 @@ This action can:
 ## Error Handling
 
 1. `图形验证码错误或已过期`:
-   fetch a new captcha and retry send-email-code.
+   for `reset` or `change_password`, fetch a new captcha and retry send-email-code.
 2. `该邮箱已被注册`:
    stop registration and switch to login if the user wants.
 3. `邮箱验证码错误或已过期`:

package/skills/clawpool-auth-access/references/api-contract.md

@@ -19,7 +19,7 @@ Helper prerequisite:
 
 | Helper Action | Method | Route | Purpose |
 |---|---|---|---|
-| `fetch-captcha` | `GET` | `/auth/captcha` | Fetch a fresh captcha before `send-email-code` |
+| `fetch-captcha` | `GET` | `/auth/captcha` | Fetch a fresh captcha before `send-email-code` for `reset` or `change_password` |
 
 ### Agent bootstrap action
 
@@ -36,7 +36,16 @@ Helper prerequisite:
 ```json
 {
   "email": "user@example.com",
-  "scene": "register",
+  "scene": "register"
+}
+```
+
+For `reset` and `change_password`, `captcha_id` and `captcha_value` are still required:
+
+```json
+{
+  "email": "user@example.com",
+  "scene": "reset",
   "captcha_id": "captcha-id",
   "captcha_value": "ab12"
 }
@@ -94,7 +103,7 @@ When the same-name `provider_type=3` agent already exists, the skill should:
 
 ### Captcha helper
 
-`fetch-captcha` returns `captcha_id` and `b64s`. The bundled script also returns `captcha_image_path` when image decoding succeeds.
+`fetch-captcha` returns `captcha_id` and `b64s`. The bundled script also returns `captcha_image_path` when image decoding succeeds. This helper is only needed for `reset` and `change_password` email-code sends.
 
 ### `register` / `login`
 
@@ -119,7 +128,7 @@ The bundled script lifts these fields to the top level:
 
 ## Common Errors
 
-1. `图形验证码错误或已过期`
+1. `图形验证码错误或已过期` for `reset` or `change_password`
 2. `邮箱验证码错误或已过期`
 3. `该邮箱已被注册`
 4. `用户不存在或密码错误`

package/skills/clawpool-auth-access/scripts/clawpool_auth.py

@@ -1231,16 +1231,28 @@ def handle_fetch_captcha(args):
 
 
 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 ClawpoolAuthError(
+                "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={
-            "email": args.email.strip(),
-            "scene": args.scene.strip(),
-            "captcha_id": args.captcha_id.strip(),
-            "captcha_value": args.captcha_value.strip(),
-        },
+        body=payload,
     )
     print_json(
         {
@@ -1409,8 +1421,8 @@ def build_parser():
     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", required=True)
-    send_email_code.add_argument("--captcha-value", required=True)
+    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")