@dhf-openclaw/grix 0.4.11 → 0.4.14

package/README.md

@@ -1,6 +1,6 @@
 # OpenClaw Grix 插件
 
-把 OpenClaw 接到 Grix（`grix.dhf.pub`）的统一插件，包含：
+把 OpenClaw 接到 Grix 服务的统一插件，默认支持正式环境，也支持本地开发地址，包含：
 
 - Grix Channel（收发消息、流式回复、`unsend`、`delete`）
 - 管理工具：`grix_query`、`grix_group`、`grix_agent_admin`
@@ -28,7 +28,7 @@ openclaw plugins enable grix
 openclaw channels add \
   --channel grix \
   --name grix-main \
-  --http-url "wss://grix.dhf.pub/v1/agent-api/ws?agent_id={agent_id}" \
+  --http-url "wss://<YOUR_GRIX_HOST>/v1/agent-api/ws?agent_id={agent_id}" \
   --user-id "<YOUR_AGENT_ID>" \
   --token "<YOUR_API_KEY>"
 ```
@@ -85,12 +85,31 @@ openclaw skills list
 
 ### 最小可用配置（单账户）
 
+线上发布示例：
+
+```json
+{
+  "channels": {
+    "grix": {
+      "enabled": true,
+      "wsUrl": "wss://<YOUR_GRIX_HOST>/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>",
+      "apiBaseUrl": "https://<YOUR_GRIX_HOST>/v1/agent-api",
+      "agentId": "<YOUR_AGENT_ID>",
+      "apiKey": "<YOUR_API_KEY>"
+    }
+  }
+}
+```
+
+本地开发示例：
+
 ```json
 {
   "channels": {
     "grix": {
       "enabled": true,
-      "wsUrl": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>",
+      "wsUrl": "ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>",
+      "apiBaseUrl": "http://127.0.0.1:27180/v1/agent-api",
       "agentId": "<YOUR_AGENT_ID>",
       "apiKey": "<YOUR_API_KEY>"
     }
@@ -110,13 +129,15 @@ openclaw skills list
         "ops": {
           "enabled": true,
           "name": "Ops",
-          "wsUrl": "wss://grix.dhf.pub/v1/agent-api/ws?agent_id=<OPS_AGENT_ID>",
+          "wsUrl": "ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=<OPS_AGENT_ID>",
+          "apiBaseUrl": "http://127.0.0.1:27180/v1/agent-api",
           "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>",
+          "wsUrl": "wss://<YOUR_GRIX_HOST>/v1/agent-api/ws?agent_id=<PROD_AGENT_ID>",
+          "apiBaseUrl": "https://<YOUR_GRIX_HOST>/v1/agent-api",
           "agentId": "<PROD_AGENT_ID>",
           "apiKey": "<PROD_API_KEY>"
         }
@@ -135,6 +156,7 @@ openclaw skills list
 | `accounts.<id>` | 否 | - | 多账户配置项，`<id>` 自定义（如 `ops`）。 |
 | `name` | 否 | - | 账户显示名。 |
 | `wsUrl` | 是（可用环境变量兜底） | `ws://127.0.0.1:27189/...`（当有 `agentId` 且未填时） | Grix WebSocket 地址。 |
+| `apiBaseUrl` | 否（可用环境变量兜底） | 优先使用显式配置；否则按同一账号的 `wsUrl` 推导；本地 `ws://127.0.0.1:27189/...` 会默认映射成 `http://127.0.0.1:27180/v1/agent-api`；只有账号自己既没配 `apiBaseUrl` 也没配 `wsUrl` 时，才回退环境变量 | Grix HTTP API 地址。开发时可单独指向本地后端。 |
 | `agentId` | 是（可用环境变量兜底） | - | Grix agent ID。 |
 | `apiKey` | 是（可用环境变量兜底） | - | Grix API Key。 |
 | `reconnectMs` | 否 | `2000` | 重连基础延迟（毫秒）。 |
@@ -160,17 +182,50 @@ openclaw skills list
 如果配置文件没填，插件会按下列环境变量读取：
 
 - `GRIX_WS_URL`
+- `GRIX_AGENT_API_BASE`
+- `GRIX_WEB_BASE_URL`
 - `GRIX_AGENT_ID`
 - `GRIX_API_KEY`
 
+注册脚本默认使用正式环境地址；如果要切到本地或其他部署，可额外设置：
+
+- `GRIX_WEB_BASE_URL`
+
+说明：
+
+- `grix_query`、`grix_group`、`grix_agent_admin` 这些 HTTP 请求会优先使用当前账号自己的 `apiBaseUrl`。
+- 如果当前账号没配 `apiBaseUrl`，会先按当前账号自己的 `wsUrl` 自动推导。
+- 只有当前账号自己既没配 `apiBaseUrl`，也没提供可用的 `wsUrl` 时，才会回退到 `GRIX_AGENT_API_BASE` 或 `GRIX_WEB_BASE_URL`。
+- `skills/grix-register/scripts/grix_auth.py` 会优先读取 `GRIX_WEB_BASE_URL`，再回落到正式环境地址；插件运行时也会把它当作 HTTP 基地址兜底。
+- 多账号混用不同环境时，不建议设置全局 `GRIX_AGENT_API_BASE` / `GRIX_WEB_BASE_URL`，否则容易把一个账号的 HTTP 请求导到另一个环境。
+- 本地开发最稳妥的写法是同时配置：
+
+```json
+{
+  "channels": {
+    "grix": {
+      "wsUrl": "ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>",
+      "apiBaseUrl": "http://127.0.0.1:27180/v1/agent-api",
+      "agentId": "<YOUR_AGENT_ID>",
+      "apiKey": "<YOUR_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_group`：`create`、`detail`、`leave`、`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`）
 
+工具调用约束：
+
+- 以上三个工具都必须显式传入 `accountId`。
+- 如果工具调用上下文存在当前连接账号，则 `accountId` 必须与上下文账号一致；不一致会直接拒绝执行。
+
 ### 运维命令
 
 查看账户：

package/dist/index.js

@@ -90,6 +90,17 @@ function resolveWsUrl(merged, agentId) {
   }
   return `ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=${encodeURIComponent(agentId)}`;
 }
+function resolveAgentAPIBaseUrl(merged) {
+  const cfgBase = normalizeNonEmpty(merged.apiBaseUrl);
+  if (cfgBase) {
+    return cfgBase;
+  }
+  if (normalizeNonEmpty(merged.wsUrl)) {
+    return "";
+  }
+  const envBase = normalizeNonEmpty(process.env.GRIX_AGENT_API_BASE);
+  return envBase;
+}
 function redactAibotWsUrl(wsUrl) {
   if (!wsUrl) {
     return "";
@@ -113,6 +124,7 @@ function resolveAibotAccount(params) {
   const agentId = normalizeAgentId(merged.agentId || process.env.GRIX_AGENT_ID);
   const apiKey = normalizeNonEmpty(merged.apiKey || process.env.GRIX_API_KEY);
   const wsUrl = resolveWsUrl(merged, agentId);
+  const apiBaseUrl = resolveAgentAPIBaseUrl(merged);
   const configured = Boolean(wsUrl && agentId && apiKey);
   return {
     accountId,
@@ -120,6 +132,7 @@ function resolveAibotAccount(params) {
     enabled,
     configured,
     wsUrl,
+    apiBaseUrl,
     agentId,
     apiKey,
     config: merged
@@ -467,6 +480,9 @@ var AibotWsClient = class {
       `reconnect scheduled in ${params.delayMs}ms attempt=${params.attempt} stable=${params.stable} authRejected=${params.authRejected} penaltyFloor=${params.penaltyFloor} suppressed=${suppressed}`
     );
   }
+  shouldLogInboundPacket(cmd) {
+    return cmd !== "ping" && cmd !== "pong" && cmd !== "send_ack";
+  }
   getStatus() {
     return { ...this.status };
   }
@@ -542,9 +558,6 @@ var AibotWsClient = class {
     if (!normalizedChannel || !normalizedAccountID || !normalizedRouteSessionKey || !normalizedSessionID) {
       throw new Error("grix session_route_bind requires channel/account_id/route_session_key/session_id");
     }
-    this.logInfo(
-      `session_route_bind request channel=${normalizedChannel} accountId=${normalizedAccountID} routeSessionKey=${normalizedRouteSessionKey} sessionId=${normalizedSessionID}`
-    );
     const packet = await this.request(
       "session_route_bind",
       {
@@ -564,9 +577,6 @@ var AibotWsClient = class {
       );
       throw this.packetError(packet);
     }
-    this.logInfo(
-      `session_route_bind ack channel=${normalizedChannel} accountId=${normalizedAccountID} routeSessionKey=${normalizedRouteSessionKey} sessionId=${normalizedSessionID}`
-    );
     return packet.payload;
   }
   async resolveSessionRoute(channel, accountId, routeSessionKey, opts = {}) {
@@ -577,9 +587,6 @@ var AibotWsClient = class {
     if (!normalizedChannel || !normalizedAccountID || !normalizedRouteSessionKey) {
       throw new Error("grix session_route_resolve requires channel/account_id/route_session_key");
     }
-    this.logInfo(
-      `session_route_resolve request channel=${normalizedChannel} accountId=${normalizedAccountID} routeSessionKey=${normalizedRouteSessionKey}`
-    );
     const packet = await this.request(
       "session_route_resolve",
       {
@@ -603,9 +610,6 @@ var AibotWsClient = class {
     if (!normalizedSessionID) {
       throw new Error("grix session_route_resolve ack missing session_id");
     }
-    this.logInfo(
-      `session_route_resolve ack channel=${normalizedChannel} accountId=${normalizedAccountID} routeSessionKey=${normalizedRouteSessionKey} sessionId=${normalizedSessionID}`
-    );
     return {
       ...payload,
       channel: String(payload.channel ?? normalizedChannel),
@@ -1058,7 +1062,7 @@ var AibotWsClient = class {
     }
     const cmd = String(packet.cmd ?? "").trim();
     const seq = Number(packet.seq ?? 0);
-    if (cmd !== "ping") {
+    if (this.shouldLogInboundPacket(cmd)) {
       this.logInfo(
         `inbound packet conn=${resolvedConnSerial} cmd=${cmd || "-"} seq=${seq} bytes=${text.length}`
       );
@@ -3656,9 +3660,6 @@ async function deliverAibotStreamBlock(params) {
     messageSid: params.messageSid,
     clientMsgId: params.clientMsgId
   });
-  params.runtime.log(
-    `[grix:${params.account.accountId}] stream block split into ${chunks.length} chunk(s) ${context} textLen=${params.text.length} chunkDelayMs=${chunkDelayMs}`
-  );
   for (let index = 0; index < chunks.length; index++) {
     if (params.abortSignal?.aborted) {
       params.runtime.log(
@@ -3671,9 +3672,6 @@ async function deliverAibotStreamBlock(params) {
     if (!normalized) {
       continue;
     }
-    params.runtime.log(
-      `[grix:${params.account.accountId}] stream chunk send ${context} chunkIndex=${index + 1}/${chunks.length} deltaLen=${normalized.length}`
-    );
     await params.client.sendStreamChunk(params.sessionId, normalized, {
       eventId: params.eventId,
       clientMsgId: params.clientMsgId,
@@ -3726,9 +3724,6 @@ async function bindSessionRouteMapping(params) {
     return;
   }
   try {
-    params.runtime.log(
-      `[grix:${params.account.accountId}] session route bind begin routeSessionKey=${routeSessionKey} sessionId=${sessionId}`
-    );
     await params.client.bindSessionRoute(
       "grix",
       params.account.accountId,
@@ -3958,9 +3953,6 @@ async function processEvent(params) {
     sessionId,
     controller: runAbortController
   });
-  runtime2.log(
-    `[grix:${account.accountId}] active reply run registered eventId=${eventId || `${sessionId}:${messageSid}`} sessionId=${sessionId} messageSid=${messageSid} activeRun=${activeRun ? "true" : "false"}`
-  );
   try {
     const route = core.channel.routing.resolveAgentRoute({
       cfg: config,
@@ -4186,22 +4178,10 @@ async function processEvent(params) {
           }
           hasSentBlock = false;
           try {
-            const finishContext = buildEventLogContext({
-              eventId,
-              sessionId,
-              messageSid,
-              clientMsgId: streamClientMsgId
-            });
             const finishDelayMs = resolveStreamFinishDelayMs(account);
             if (finishDelayMs > 0) {
-              runtime2.log(
-                `[grix:${account.accountId}] stream finish delay ${finishContext} delayMs=${finishDelayMs}`
-              );
               await sleep2(finishDelayMs);
             }
-            runtime2.log(
-              `[grix:${account.accountId}] stream finish ${finishContext}`
-            );
             await client.sendStreamChunk(sessionId, "", {
               eventId,
               clientMsgId: streamClientMsgId,
@@ -4235,9 +4215,12 @@ async function processEvent(params) {
                 clientMsgId: info.kind === "block" ? streamClientMsgId : `reply_${messageSid}_${outboundCounter}`,
                 outboundCounter
               });
-              runtime2.log(
-                `[grix:${account.accountId}] deliver ${deliverContext} kind=${info.kind} textLen=${text.length} hasMedia=${hasMedia} streamedBefore=${streamedTextAlreadyVisible}`
-              );
+              const isStreamBlock = info.kind === "block" && !guardedText && !hasMedia && text.length > 0;
+              if (!isStreamBlock) {
+                runtime2.log(
+                  `[grix:${account.accountId}] deliver ${deliverContext} kind=${info.kind} textLen=${text.length} hasMedia=${hasMedia} streamedBefore=${streamedTextAlreadyVisible}`
+                );
+              }
               if (guardedText) {
                 runtime2.error(
                   `[grix:${account.accountId}] rewrite internal reply text ${deliverContext} code=${guardedText.code} raw=${JSON.stringify(guardedText.rawText)}`
@@ -4256,7 +4239,7 @@ async function processEvent(params) {
                 );
                 return;
               }
-              if (info.kind === "block" && !guardedText && !hasMedia && text) {
+              if (isStreamBlock) {
                 const didSendBlock = await deliverAibotStreamBlock({
                   text,
                   client,
@@ -4407,7 +4390,7 @@ async function processEvent(params) {
     }
   } finally {
     runtime2.log(
-      `[grix:${account.accountId}] active reply run clearing eventId=${activeRun?.eventId || "-"} sessionId=${activeRun?.sessionId || sessionId} stopRequested=${activeRun?.stopRequested === true} abortReason=${activeRun ? resolveAbortReason(activeRun.controller.signal) : "-"} visibleOutputSent=${visibleOutputSent}`
+      `[grix:${account.accountId}] active reply run clearing eventId=${activeRun?.eventId || "-"} stopRequested=${activeRun?.stopRequested === true} abortReason=${activeRun ? resolveAbortReason(activeRun.controller.signal) : "-"} visibleOutputSent=${visibleOutputSent}`
     );
     clearActiveReplyRun(activeRun);
     if (!inboundEventAccepted) {
@@ -4602,7 +4585,7 @@ var meta = {
   label: "Grix",
   selectionLabel: "Grix",
   docsPath: "/channels/grix",
-  blurb: "Connect OpenClaw to grix.dhf.pub for OpenClaw website management with mobile PWA support.",
+  blurb: "Connect OpenClaw to a Grix deployment for website management with mobile PWA support.",
   aliases: ["gr"],
   order: 90
 };
@@ -4715,6 +4698,7 @@ var aibotPlugin = {
       clearBaseFields: [
         "name",
         "wsUrl",
+        "apiBaseUrl",
         "agentId",
         "apiKey",
         "reconnectMs",
@@ -5309,6 +5293,17 @@ function buildGroupMemberAddRequest(params) {
     body
   };
 }
+function buildGroupLeaveSelfRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  return {
+    actionName: "group_leave_self",
+    method: "POST",
+    path: "/sessions/leave",
+    body: {
+      session_id: sessionID
+    }
+  };
+}
 function buildGroupMemberRemoveRequest(params) {
   const sessionID = readRequiredStringParam(params, "sessionId");
   const memberIDs = readNumericIDArray(params, "memberIds", true);
@@ -5516,6 +5511,8 @@ function buildAgentHTTPRequest(action, params) {
       return buildMessageHistoryRequest(params);
     case "group_create":
       return buildGroupCreateRequest(params);
+    case "group_leave_self":
+      return buildGroupLeaveSelfRequest(params);
     case "group_member_add":
       return buildGroupMemberAddRequest(params);
     case "group_member_remove":
@@ -5539,13 +5536,19 @@ function buildAgentHTTPRequest(action, params) {
 
 // src/admin/agent-api-http.ts
 var DEFAULT_HTTP_TIMEOUT_MS = 15e3;
+var MAX_LOG_KEYS = 8;
+var MAX_LOG_PAYLOAD_CHARS = 1200;
 function trimTrailingSlash(value) {
   return value.replace(/\/+$/, "");
 }
+function logAgentAPIInfo(message) {
+  console.info(`[grix:agent-api] ${message}`);
+}
+function logAgentAPIError(message) {
+  console.error(`[grix:agent-api] ${message}`);
+}
 function resolveExplicitAgentAPIBase() {
-  const base = String(
-    process.env.GRIX_AGENT_API_BASE ?? process.env.AIBOT_AGENT_API_BASE ?? ""
-  ).trim();
+  const base = String(process.env.GRIX_AGENT_API_BASE ?? "").trim();
   if (!base) {
     return "";
   }
@@ -5595,16 +5598,39 @@ function deriveLocalAgentAPIBaseFromWsUrl(wsUrl) {
   const protocol = parsed.protocol === "wss:" ? "https:" : "http:";
   return trimTrailingSlash(`${protocol}//${parsed.hostname}:${apiPort}`) + "/v1/agent-api";
 }
-function resolveAgentAPIBase(account) {
-  const explicit = resolveExplicitAgentAPIBase();
-  if (explicit) {
-    return explicit;
+function resolveAgentAPIBaseInfo(account) {
+  const accountBase = trimTrailingSlash(String(account.apiBaseUrl ?? "").trim());
+  if (accountBase) {
+    return {
+      base: accountBase,
+      source: "account_api_base_url"
+    };
   }
-  const local = deriveLocalAgentAPIBaseFromWsUrl(account.wsUrl);
+  const normalizedWsUrl = String(account.wsUrl ?? "").trim();
+  const local = deriveLocalAgentAPIBaseFromWsUrl(normalizedWsUrl);
   if (local) {
-    return local;
+    return {
+      base: local,
+      source: "local_ws_url"
+    };
+  }
+  if (normalizedWsUrl) {
+    return {
+      base: deriveAgentAPIBaseFromWsUrl(normalizedWsUrl),
+      source: "derived_from_ws_url"
+    };
+  }
+  const explicit = resolveExplicitAgentAPIBase();
+  if (explicit) {
+    return {
+      base: explicit,
+      source: "env_grix_agent_api_base"
+    };
   }
-  return deriveAgentAPIBaseFromWsUrl(account.wsUrl);
+  return {
+    base: deriveAgentAPIBaseFromWsUrl(normalizedWsUrl),
+    source: "derived_from_ws_url"
+  };
 }
 function buildRequestURL(base, path, query) {
   const normalizedPath = path.startsWith("/") ? path : `/${path}`;
@@ -5647,10 +5673,105 @@ function extractNetworkErrorMessage(error) {
   }
   return String(error);
 }
+function buildAPIKeyState(apiKey) {
+  const normalized = String(apiKey ?? "").trim();
+  if (!normalized) {
+    return "empty";
+  }
+  return "present";
+}
+function summarizePayloadKeys(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return "none";
+  }
+  const keys = Object.keys(payload).map((k) => String(k).trim()).filter(Boolean).sort();
+  if (!keys.length) {
+    return "none";
+  }
+  const limited = keys.slice(0, MAX_LOG_KEYS);
+  if (keys.length <= MAX_LOG_KEYS) {
+    return limited.join(",");
+  }
+  return `${limited.join(",")}...(total=${keys.length})`;
+}
+function summarizePayloadBytes(payload) {
+  try {
+    return String(Buffer.byteLength(JSON.stringify(payload ?? {}), "utf8"));
+  } catch {
+    return "unknown";
+  }
+}
+function isSensitiveLogKey(key) {
+  const normalized = String(key ?? "").trim().toLowerCase();
+  return normalized.includes("api_key") || normalized.includes("apikey") || normalized.includes("token") || normalized.includes("authorization") || normalized.includes("password") || normalized.includes("secret");
+}
+function sanitizePayloadForLog(payload, depth = 0) {
+  if (depth >= 5) {
+    return "[max-depth]";
+  }
+  if (payload == null) {
+    return payload;
+  }
+  if (typeof payload === "string" || typeof payload === "number" || typeof payload === "boolean") {
+    return payload;
+  }
+  if (Array.isArray(payload)) {
+    return payload.map((item) => sanitizePayloadForLog(item, depth + 1));
+  }
+  if (typeof payload === "object") {
+    const raw = payload;
+    const sanitized = {};
+    for (const [key, value] of Object.entries(raw)) {
+      sanitized[key] = isSensitiveLogKey(key) ? "<redacted>" : sanitizePayloadForLog(value, depth + 1);
+    }
+    return sanitized;
+  }
+  return String(payload);
+}
+function stringifyPayloadForLog(payload) {
+  let json = "";
+  try {
+    json = JSON.stringify(sanitizePayloadForLog(payload));
+  } catch {
+    return '"[unserializable]"';
+  }
+  if (!json) {
+    return "{}";
+  }
+  if (json.length <= MAX_LOG_PAYLOAD_CHARS) {
+    return json;
+  }
+  return `${json.slice(0, MAX_LOG_PAYLOAD_CHARS)}...(truncated,len=${json.length})`;
+}
+function buildRequestLogContext(params, context) {
+  const queryPayload = params.query ?? {};
+  const bodyPayload = params.method === "POST" ? params.body ?? {} : {};
+  return [
+    `action=${params.actionName}`,
+    `account=${params.account.accountId}`,
+    `agent=${params.account.agentId}`,
+    `method=${params.method}`,
+    `source=${context.resolvedBase.source}`,
+    `url=${context.url}`,
+    `timeout_ms=${context.timeoutMs}`,
+    `api_key=${buildAPIKeyState(params.account.apiKey)}`,
+    `query_keys=${summarizePayloadKeys(queryPayload)}`,
+    `query_payload=${JSON.stringify(stringifyPayloadForLog(queryPayload))}`,
+    `body_keys=${summarizePayloadKeys(bodyPayload)}`,
+    `body_payload=${JSON.stringify(stringifyPayloadForLog(bodyPayload))}`,
+    `body_bytes=${summarizePayloadBytes(bodyPayload)}`
+  ].join(" ");
+}
 async function callAgentAPI(params) {
-  const base = resolveAgentAPIBase(params.account);
-  const url = buildRequestURL(base, params.path, params.query);
+  const resolvedBase = resolveAgentAPIBaseInfo(params.account);
+  const url = buildRequestURL(resolvedBase.base, params.path, params.query);
   const timeoutMs = Number.isFinite(params.timeoutMs) ? Math.max(1e3, Math.floor(params.timeoutMs)) : DEFAULT_HTTP_TIMEOUT_MS;
+  const requestLogContext = buildRequestLogContext(params, {
+    resolvedBase,
+    url,
+    timeoutMs
+  });
+  logAgentAPIInfo(`request ${requestLogContext}`);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   let resp;
@@ -5666,6 +5787,9 @@ async function callAgentAPI(params) {
     });
   } catch (error) {
     clearTimeout(timer);
+    logAgentAPIError(
+      `network_error ${requestLogContext} error=${JSON.stringify(extractNetworkErrorMessage(error))}`
+    );
     throw new Error(
       `Grix ${params.actionName} network error: ${extractNetworkErrorMessage(error)}`
     );
@@ -5677,6 +5801,9 @@ async function callAgentAPI(params) {
   try {
     envelope = JSON.parse(rawBody);
   } catch {
+    logAgentAPIError(
+      `invalid_response ${requestLogContext} status=${status} raw_len=${rawBody.length}`
+    );
     throw new Error(
       `Grix ${params.actionName} invalid response: status=${status} body=${rawBody.slice(0, 256)}`
     );
@@ -5684,13 +5811,41 @@ async function callAgentAPI(params) {
   const bizCode = normalizeBizCode(envelope.code);
   if (!resp.ok || bizCode !== 0) {
     const message = normalizeMessage(envelope.msg);
+    logAgentAPIError(
+      `failed ${requestLogContext} status=${status} code=${bizCode} msg=${message} has_data=${envelope.data == null ? "false" : "true"}`
+    );
     throw new Error(
       `Grix ${params.actionName} failed: status=${status} code=${bizCode} msg=${message}`
     );
   }
+  logAgentAPIInfo(`success ${requestLogContext} status=${status}`);
   return envelope.data;
 }
 
+// src/admin/account-binding.ts
+function normalizeNonEmpty2(value) {
+  const normalized = String(value ?? "").trim();
+  return normalized || void 0;
+}
+function resolveStrictToolAccountId(params) {
+  const toolAccountId = normalizeNonEmpty2(params.toolAccountId);
+  const contextAccountId = normalizeNonEmpty2(params.contextAccountId);
+  console.info(
+    `[grix:account-binding] tool=${params.toolName} request_account=${toolAccountId ?? "-"} context_account=${contextAccountId ?? "-"}`
+  );
+  if (!toolAccountId) {
+    throw new Error(
+      `[${params.toolName}] accountId is required. Pass the exact accountId of the current connection.`
+    );
+  }
+  if (contextAccountId && toolAccountId !== contextAccountId) {
+    throw new Error(
+      `[${params.toolName}] accountId mismatch. request=${toolAccountId}, context=${contextAccountId}. Refusing cross-account execution.`
+    );
+  }
+  return toolAccountId;
+}
+
 // src/admin/accounts.ts
 var DEFAULT_ACCOUNT_ID2 = "default";
 function normalizeAccountId2(value) {
@@ -5711,9 +5866,24 @@ function listConfiguredAccountIds2(cfg) {
   }
   return Object.keys(accounts).filter(Boolean);
 }
-function normalizeNonEmpty2(value) {
+function normalizeNonEmpty3(value) {
   return String(value ?? "").trim();
 }
+function trimTrailingSlash2(value) {
+  return value.replace(/\/+$/, "");
+}
+function summarizeEndpoint(value) {
+  const normalized = normalizeNonEmpty3(value);
+  if (!normalized) {
+    return "-";
+  }
+  try {
+    const parsed = new URL(normalized);
+    return `${parsed.protocol}//${parsed.host}`;
+  } catch {
+    return normalized.slice(0, 128);
+  }
+}
 function appendAgentIdToWsUrl2(rawWsUrl, agentId) {
   if (!rawWsUrl) {
     return "";
@@ -5736,8 +5906,8 @@ function appendAgentIdToWsUrl2(rawWsUrl, agentId) {
   }
 }
 function resolveWsUrl2(merged, agentId) {
-  const envWs = normalizeNonEmpty2(process.env.GRIX_WS_URL);
-  const cfgWs = normalizeNonEmpty2(merged.wsUrl);
+  const envWs = normalizeNonEmpty3(process.env.GRIX_WS_URL);
+  const cfgWs = normalizeNonEmpty3(merged.wsUrl);
   const ws = cfgWs || envWs;
   if (ws) {
     return appendAgentIdToWsUrl2(ws, agentId);
@@ -5747,6 +5917,44 @@ function resolveWsUrl2(merged, agentId) {
   }
   return `ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=${encodeURIComponent(agentId)}`;
 }
+function resolveAgentAPIBaseUrl2(merged) {
+  const cfgBase = trimTrailingSlash2(normalizeNonEmpty3(merged.apiBaseUrl));
+  if (cfgBase) {
+    return cfgBase;
+  }
+  if (normalizeNonEmpty3(merged.wsUrl)) {
+    return "";
+  }
+  const envBase = trimTrailingSlash2(normalizeNonEmpty3(process.env.GRIX_AGENT_API_BASE));
+  const webBase = trimTrailingSlash2(normalizeNonEmpty3(process.env.GRIX_WEB_BASE_URL));
+  return envBase || webBase;
+}
+function resolveStrictAccountConfig(cfg, accountId) {
+  const grixCfg = rawGrixConfig(cfg);
+  const accounts = grixCfg.accounts;
+  if (!accounts || typeof accounts !== "object") {
+    console.error(
+      `[grix:account] strict lookup failed account=${accountId} reason=accounts_map_missing`
+    );
+    throw new Error(
+      `Grix account "${accountId}" is not configured under channels.grix.accounts.`
+    );
+  }
+  const configuredIds = Object.keys(accounts).filter(Boolean).sort();
+  const account = accounts[accountId];
+  if (!account || typeof account !== "object") {
+    console.error(
+      `[grix:account] strict lookup failed account=${accountId} reason=account_missing configured_accounts=${configuredIds.join(",") || "none"}`
+    );
+    throw new Error(
+      `Grix account "${accountId}" is missing under channels.grix.accounts.${accountId}.`
+    );
+  }
+  console.info(
+    `[grix:account] strict lookup account=${accountId} configured_accounts=${configuredIds.join(",") || "none"} has_ws=${normalizeNonEmpty3(account.wsUrl) ? "yes" : "no"} has_api_base=${normalizeNonEmpty3(account.apiBaseUrl) ? "yes" : "no"} has_agent_id=${normalizeNonEmpty3(account.agentId) ? "yes" : "no"} has_api_key=${normalizeNonEmpty3(account.apiKey) ? "yes" : "no"}`
+  );
+  return account;
+}
 function resolveMergedAccountConfig(cfg, accountId) {
   const grixCfg = rawGrixConfig(cfg);
   const { accounts: _ignoredAccounts, defaultAccount: _ignoredDefault, ...base } = grixCfg;
@@ -5776,21 +5984,29 @@ function resolveDefaultGrixAccountId(cfg) {
   return ids[0] ?? DEFAULT_ACCOUNT_ID2;
 }
 function resolveGrixAccount(params) {
+  const strictScope = Boolean(params.strictAccountScope);
   const accountId = params.accountId == null || String(params.accountId).trim() === "" ? resolveDefaultGrixAccountId(params.cfg) : normalizeAccountId2(params.accountId);
-  const merged = resolveMergedAccountConfig(params.cfg, accountId);
+  const merged = strictScope ? resolveStrictAccountConfig(params.cfg, accountId) : resolveMergedAccountConfig(params.cfg, accountId);
   const baseEnabled = rawGrixConfig(params.cfg).enabled !== false;
   const accountEnabled = merged.enabled !== false;
   const enabled = baseEnabled && accountEnabled;
-  const agentId = normalizeNonEmpty2(merged.agentId || process.env.GRIX_AGENT_ID);
-  const apiKey = normalizeNonEmpty2(merged.apiKey || process.env.GRIX_API_KEY);
-  const wsUrl = resolveWsUrl2(merged, agentId);
+  const agentId = strictScope ? normalizeNonEmpty3(merged.agentId) : normalizeNonEmpty3(merged.agentId || process.env.GRIX_AGENT_ID);
+  const apiKey = strictScope ? normalizeNonEmpty3(merged.apiKey) : normalizeNonEmpty3(merged.apiKey || process.env.GRIX_API_KEY);
+  const wsUrl = strictScope ? appendAgentIdToWsUrl2(normalizeNonEmpty3(merged.wsUrl), agentId) : resolveWsUrl2(merged, agentId);
+  const apiBaseUrl = strictScope ? trimTrailingSlash2(normalizeNonEmpty3(merged.apiBaseUrl)) : resolveAgentAPIBaseUrl2(merged);
   const configured = Boolean(wsUrl && agentId && apiKey);
+  if (strictScope) {
+    console.info(
+      `[grix:account] strict resolved account=${accountId} enabled=${enabled} configured=${configured} ws_endpoint=${summarizeEndpoint(wsUrl)} api_base_endpoint=${summarizeEndpoint(apiBaseUrl)} agent_id=${agentId || "-"} api_key=${apiKey ? "present" : "empty"}`
+    );
+  }
   return {
     accountId,
-    name: normalizeNonEmpty2(merged.name) || void 0,
+    name: normalizeNonEmpty3(merged.name) || void 0,
     enabled,
     configured,
     wsUrl,
+    apiBaseUrl,
     agentId,
     apiKey,
     config: merged
@@ -5805,6 +6021,7 @@ function summarizeGrixAccounts(cfg) {
       enabled: account.enabled,
       configured: account.configured,
       wsUrl: account.wsUrl || null,
+      apiBaseUrl: account.apiBaseUrl || null,
       agentId: account.agentId || null
     };
   });
@@ -5842,9 +6059,15 @@ function sanitizeCreatedAgentData(data) {
   return payload;
 }
 async function createGrixApiAgent(params) {
+  const accountId = resolveStrictToolAccountId({
+    toolName: "grix_agent_admin",
+    toolAccountId: params.toolParams.accountId,
+    contextAccountId: params.contextAccountId
+  });
   const account = resolveGrixAccount({
     cfg: params.cfg,
-    accountId: params.toolParams.accountId
+    accountId,
+    strictAccountScope: true
   });
   if (!account.enabled) {
     throw new Error(`Grix account "${account.accountId}" is disabled.`);
@@ -5968,9 +6191,10 @@ var GrixAgentAdminToolSchema = {
       required: ["actions"]
     }
   },
-  required: ["agentName", "describeMessageTool"]
+  required: ["accountId", "agentName", "describeMessageTool"]
 };
-function createGrixAgentAdminTool(api) {
+function createGrixAgentAdminTool(api, ctx) {
+  const contextAccountId = ctx?.agentAccountId;
   return {
     name: "grix_agent_admin",
     label: "Grix Agent Admin",
@@ -5981,7 +6205,8 @@ function createGrixAgentAdminTool(api) {
         return jsonToolResult(
           await createGrixApiAgent({
             cfg: api.config,
-            toolParams: params
+            toolParams: params,
+            contextAccountId
           })
         );
       } catch (err) {
@@ -6000,6 +6225,8 @@ function mapGroupActionToRequestAction(action) {
       return "group_create";
     case "detail":
       return "group_detail_read";
+    case "leave":
+      return "group_leave_self";
     case "add_members":
       return "group_member_add";
     case "remove_members":
@@ -6018,9 +6245,15 @@ function mapGroupActionToRequestAction(action) {
   }
 }
 async function runGrixGroupAction(params) {
+  const accountId = resolveStrictToolAccountId({
+    toolName: "grix_group",
+    toolAccountId: params.toolParams.accountId,
+    contextAccountId: params.contextAccountId
+  });
   const account = resolveGrixAccount({
     cfg: params.cfg,
-    accountId: params.toolParams.accountId
+    accountId,
+    strictAccountScope: true
   });
   if (!account.enabled) {
     throw new Error(`Grix account "${account.accountId}" is disabled.`);
@@ -6038,6 +6271,13 @@ async function runGrixGroupAction(params) {
     query: request.query,
     body: request.body
   });
+  if (params.toolParams.action === "leave") {
+    const d = data;
+    const left = d != null && typeof d === "object" ? d["left"] : void 0;
+    console.info(
+      `[grix:group] leave result account=${account.accountId} agent=${account.agentId} session=${String(params.toolParams.sessionId ?? "")} left=${left}`
+    );
+  }
   return {
     ok: true,
     accountId: account.accountId,
@@ -6063,7 +6303,7 @@ var GrixGroupToolSchema = {
         memberIds: { type: "array", items: numericIdSchema },
         memberTypes: { type: "array", items: { type: "integer", enum: [1, 2] } }
       },
-      required: ["action", "name"]
+      required: ["action", "accountId", "name"]
     },
     {
       type: "object",
@@ -6073,7 +6313,17 @@ var GrixGroupToolSchema = {
         accountId: { type: "string", minLength: 1 },
         sessionId: { type: "string", minLength: 1 }
       },
-      required: ["action", "sessionId"]
+      required: ["action", "accountId", "sessionId"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "leave" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 }
+      },
+      required: ["action", "accountId", "sessionId"]
     },
     {
       type: "object",
@@ -6085,7 +6335,7 @@ var GrixGroupToolSchema = {
         memberIds: { type: "array", items: numericIdSchema, minItems: 1 },
         memberTypes: { type: "array", items: { type: "integer", enum: [1, 2] } }
       },
-      required: ["action", "sessionId", "memberIds"]
+      required: ["action", "accountId", "sessionId", "memberIds"]
     },
     {
       type: "object",
@@ -6097,7 +6347,7 @@ var GrixGroupToolSchema = {
         memberIds: { type: "array", items: numericIdSchema, minItems: 1 },
         memberTypes: { type: "array", items: { type: "integer", enum: [1, 2] } }
       },
-      required: ["action", "sessionId", "memberIds"]
+      required: ["action", "accountId", "sessionId", "memberIds"]
     },
     {
       type: "object",
@@ -6110,7 +6360,7 @@ var GrixGroupToolSchema = {
         memberType: { type: "integer", enum: [1] },
         role: { type: "integer", enum: [1, 2] }
       },
-      required: ["action", "sessionId", "memberId", "role"]
+      required: ["action", "accountId", "sessionId", "memberId", "role"]
     },
     {
       type: "object",
@@ -6121,7 +6371,7 @@ var GrixGroupToolSchema = {
         sessionId: { type: "string", minLength: 1 },
         allMembersMuted: { type: "boolean" }
       },
-      required: ["action", "sessionId", "allMembersMuted"]
+      required: ["action", "accountId", "sessionId", "allMembersMuted"]
     },
     {
       type: "object",
@@ -6135,7 +6385,7 @@ var GrixGroupToolSchema = {
         isSpeakMuted: { type: "boolean" },
         canSpeakWhenAllMuted: { type: "boolean" }
       },
-      required: ["action", "sessionId", "memberId"],
+      required: ["action", "accountId", "sessionId", "memberId"],
       anyOf: [
         { required: ["isSpeakMuted"] },
         { required: ["canSpeakWhenAllMuted"] }
@@ -6149,11 +6399,12 @@ var GrixGroupToolSchema = {
         accountId: { type: "string", minLength: 1 },
         sessionId: { type: "string", minLength: 1 }
       },
-      required: ["action", "sessionId"]
+      required: ["action", "accountId", "sessionId"]
     }
   ]
 };
-function createGrixGroupTool(api) {
+function createGrixGroupTool(api, ctx) {
+  const contextAccountId = ctx?.agentAccountId;
   return {
     name: "grix_group",
     label: "Grix Group",
@@ -6164,7 +6415,8 @@ function createGrixGroupTool(api) {
         return jsonToolResult(
           await runGrixGroupAction({
             cfg: api.config,
-            toolParams: params
+            toolParams: params,
+            contextAccountId
           })
         );
       } catch (err) {
@@ -6191,9 +6443,15 @@ function mapQueryActionToRequestAction(action) {
   }
 }
 async function runGrixQueryAction(params) {
+  const accountId = resolveStrictToolAccountId({
+    toolName: "grix_query",
+    toolAccountId: params.toolParams.accountId,
+    contextAccountId: params.contextAccountId
+  });
   const account = resolveGrixAccount({
     cfg: params.cfg,
-    accountId: params.toolParams.accountId
+    accountId,
+    strictAccountScope: true
   });
   if (!account.enabled) {
     throw new Error(`Grix account "${account.accountId}" is disabled.`);
@@ -6232,7 +6490,7 @@ var GrixQueryToolSchema = {
         limit: { type: "integer", minimum: 1 },
         offset: { type: "integer", minimum: 0 }
       },
-      required: ["action", "id"]
+      required: ["action", "accountId", "id"]
     },
     {
       type: "object",
@@ -6244,7 +6502,7 @@ var GrixQueryToolSchema = {
         limit: { type: "integer", minimum: 1 },
         offset: { type: "integer", minimum: 0 }
       },
-      required: ["action", "id"]
+      required: ["action", "accountId", "id"]
     },
     {
       type: "object",
@@ -6256,11 +6514,12 @@ var GrixQueryToolSchema = {
         beforeId: { type: "string", pattern: "^[0-9]+$" },
         limit: { type: "integer", minimum: 1 }
       },
-      required: ["action", "sessionId"]
+      required: ["action", "accountId", "sessionId"]
     }
   ]
 };
-function createGrixQueryTool(api) {
+function createGrixQueryTool(api, ctx) {
+  const contextAccountId = ctx?.agentAccountId;
   return {
     name: "grix_query",
     label: "Grix Query",
@@ -6271,7 +6530,8 @@ function createGrixQueryTool(api) {
         return jsonToolResult(
           await runGrixQueryAction({
             cfg: api.config,
-            toolParams: params
+            toolParams: params,
+            contextAccountId
           })
         );
       } catch (err) {
@@ -6364,9 +6624,9 @@ var plugin = {
   register(api) {
     setAibotRuntime(api.runtime);
     api.registerChannel({ plugin: aibotPlugin });
-    api.registerTool(createGrixQueryTool(api), { optional: true });
-    api.registerTool(createGrixGroupTool(api), { optional: true });
-    api.registerTool(createGrixAgentAdminTool(api), { optional: true });
+    api.registerTool((ctx) => createGrixQueryTool(api, ctx), { optional: true });
+    api.registerTool((ctx) => createGrixGroupTool(api, ctx), { optional: true });
+    api.registerTool((ctx) => createGrixAgentAdminTool(api, ctx), { optional: true });
     api.registerCli(({ program }) => registerGrixAdminCli({ api, program }), {
       commands: ["grix"]
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhf-openclaw/grix",
-  "version": "0.4.11",
+  "version": "0.4.14",
   "description": "Unified Grix OpenClaw plugin with channel transport, typed admin tools, and operator CLI",
   "type": "module",
   "main": "./dist/index.js",
@@ -60,7 +60,7 @@
       "label": "Grix",
       "selectionLabel": "Grix",
       "docsPath": "/channels/grix",
-      "blurb": "Connect OpenClaw to grix.dhf.pub for OpenClaw website management with mobile PWA support.",
+      "blurb": "Connect OpenClaw to a Grix deployment for website management with mobile PWA support.",
       "aliases": [
         "gr"
       ],

package/skills/grix-group/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use the typed `grix_group` tool for Grix group lifecycle and membership operations. Trigger when users ask to create, inspect, leave, update, or dissolve groups, or when these operations fail with scope or permission errors.
 ---
 
 # Grix Group Governance
@@ -11,7 +11,7 @@ This skill is about tool selection and guardrails, not protocol bridging.
 ## Workflow
 
 1. Parse the user request into one action:
-   `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, or `dissolve`.
+   `create`, `detail`, `leave`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, or `dissolve`.
 2. Validate required fields before any call.
 3. Call `grix_group` exactly once per business action.
 4. Classify failures by HTTP/BizCode and return exact remediation.
@@ -23,8 +23,8 @@ This skill is about tool selection and guardrails, not protocol bridging.
 For Grix group governance, always call:
 
 1. Tool: `grix_group`
-2. `action`: one of `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, `dissolve`
-3. `accountId`: optional; include it when the configured account is ambiguous
+2. `action`: one of `create`, `detail`, `leave`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, `dissolve`
+3. `accountId`: always pass `{{AccountId}}` from the current conversation context for every action, including `leave`.
 
 Rules:
 
@@ -67,6 +67,24 @@ Guardrails:
 2. Reject non-numeric `memberIds` before calling the tool.
 3. If `sessionId` is ambiguous, ask the user to confirm the target group first.
 
+### leave
+
+Purpose: let the current Agent leave a group by itself.
+
+Required input:
+
+1. `sessionId`
+
+Guardrails:
+
+1. Only the current Agent owner can request this action.
+2. If the requester is not the current Agent owner, reject the request directly and do not call `grix_group`.
+3. This action is only for the current Agent leaving its own group membership.
+4. Never translate a request to remove other members into `leave`; use `remove_members` for that.
+5. Do not send `memberId`, `memberIds`, or `memberTypes` with this action.
+6. This action does not require scope and should not be described as a scope-grant workflow.
+7. Execute `leave` silently: do not send any pre-leave or farewell message to the group before leaving.
+
 ### remove_members
 
 Required input:
@@ -123,6 +141,7 @@ Required input:
 
 1. `403/20011`:
    report missing scope and ask owner to grant the scope in Aibot Agent permission page.
+   Do not use this remediation for `leave`, because `leave` is scope-free.
 2. `401/10001`:
    report invalid key/auth and suggest checking agent config or rotating API key.
 3. `403/10002`:
@@ -138,6 +157,7 @@ Required input:
 2. Include key identifiers (`session_id`, member count, mute state) when successful.
 3. Include exact remediation when failed.
 4. Never hide scope or auth errors behind generic wording.
+5. For `leave`, report result to the requester only; do not post extra messages into the group session.
 
 ## References
 

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

@@ -16,6 +16,7 @@ Map high-level governance actions to Aibot Agent API HTTP routes.
 | Action | Method | Route | Required Scope |
 |---|---|---|---|
 | `group_create` | `POST` | `/sessions/create_group` | `group.create` |
+| `group_leave_self` | `POST` | `/sessions/leave` | - |
 | `group_member_add` | `POST` | `/sessions/members/add` | `group.member.add` |
 
 ## OpenClaw Tool Mapping
@@ -26,6 +27,7 @@ Use the native `grix_group` tool with typed fields:
 |---|---|---|
 | `create` | `group_create` | `name` |
 | `detail` | `group_detail_read` | `sessionId` |
+| `leave` | `group_leave_self` | `sessionId` |
 | `add_members` | `group_member_add` | `sessionId`, `memberIds` |
 | `remove_members` | `group_member_remove` | `sessionId`, `memberIds` |
 | `update_member_role` | `group_member_role_update` | `sessionId`, `memberId`, `role` |
@@ -57,6 +59,15 @@ Use the native `grix_group` tool with typed fields:
 }
 ```
 
+### leave
+
+```json
+{
+  "action": "leave",
+  "sessionId": "task_room_9083"
+}
+```
+
 ## Error Matrix
 
 | HTTP/BizCode | Meaning | Skill Response |
@@ -66,6 +77,10 @@ Use the native `grix_group` tool with typed fields:
 | `401/10001` | invalid or missing auth | Check api_key and account config |
 | `403/10002` | agent not active / invalid provider | Ask owner to activate the agent |
 
+Notes:
+
+1. `leave` does not require scope and should not route `403/20011` into scope remediation.
+
 ## Retry Policy
 
 1. Never auto-retry `group_create` unless user confirms.

package/skills/grix-register/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grix-register
-description: 仅用于初次安装阶段，完成 grix.dhf.pub 账号注册/登录并拿到第一个 provider_type=3 Agent 的参数；本技能不做任何本地 OpenClaw 配置。
+description: 仅用于初次安装阶段，完成 Grix 环境的账号注册/登录并拿到第一个 provider_type=3 Agent 的参数；本技能不做任何本地 OpenClaw 配置。
 ---
 
 # Grix Register

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

@@ -8,8 +8,9 @@
 
 ## Base
 
-1. Website: `https://grix.dhf.pub/`
-2. Public Grix API base: `https://grix.dhf.pub/v1`
+1. Default website: `https://grix.dhf.pub/`
+2. Default public Grix API base: `https://grix.dhf.pub/v1`
+3. Local development or private deployment can override the base URL.
 
 ## Route Mapping
 

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

@@ -13,7 +13,24 @@ import uuid
 
 DEFAULT_BASE_URL = "https://grix.dhf.pub"
 DEFAULT_TIMEOUT_SECONDS = 15
-DEFAULT_PORTAL_URL = "https://grix.dhf.pub/"
+
+
+def resolve_default_base_url() -> str:
+    return (os.environ.get("GRIX_WEB_BASE_URL", "") or "").strip() or DEFAULT_BASE_URL
+
+
+def derive_portal_url(raw_base_url: str) -> str:
+    base = (raw_base_url or "").strip() or resolve_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 path.endswith("/v1"):
+        path = path[: -len("/v1")]
+
+    normalized = parsed._replace(path=path or "/", params="", query="", fragment="")
+    return urllib.parse.urlunparse(normalized).rstrip("/") + "/"
 
 
 class GrixAuthError(RuntimeError):
@@ -25,7 +42,7 @@ class GrixAuthError(RuntimeError):
 
 
 def normalize_base_url(raw_base_url: str) -> str:
-    base = (raw_base_url or "").strip() or DEFAULT_BASE_URL
+    base = (raw_base_url or "").strip() or resolve_default_base_url()
     parsed = urllib.parse.urlparse(base)
     if not parsed.scheme or not parsed.netloc:
         raise ValueError(f"Invalid base URL: {base}")
@@ -112,7 +129,7 @@ def print_json(payload):
     sys.stdout.write("\n")
 
 
-def build_auth_result(action: str, result: dict):
+def build_auth_result(action: str, result: dict, base_url: str):
     data = result.get("data") or {}
     user = data.get("user") or {}
     return {
@@ -123,7 +140,7 @@ def build_auth_result(action: str, result: dict):
         "refresh_token": data.get("refresh_token", ""),
         "expires_in": data.get("expires_in", 0),
         "user_id": user.get("id", ""),
-        "portal_url": DEFAULT_PORTAL_URL,
+        "portal_url": derive_portal_url(base_url),
         "data": data,
     }
 
@@ -170,7 +187,7 @@ def login_with_credentials(base_url: str, account: str, password: str, device_id
             "platform": platform,
         },
     )
-    return build_auth_result("login", result)
+    return build_auth_result("login", result, base_url)
 
 
 def create_api_agent(base_url: str, access_token: str, agent_name: str, avatar_url: str):
@@ -338,7 +355,7 @@ def handle_register(args):
             "platform": platform,
         },
     )
-    print_json(build_auth_result("register", result))
+    print_json(build_auth_result("register", result, args.base_url))
 
 
 def handle_login(args):
@@ -374,7 +391,11 @@ def handle_create_api_agent(args):
 
 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")
+    parser.add_argument(
+        "--base-url",
+        default=resolve_default_base_url(),
+        help="Grix web base URL (defaults to GRIX_WEB_BASE_URL or https://grix.dhf.pub)",
+    )
 
     subparsers = parser.add_subparsers(dest="action", required=True)