@dhf-openclaw/grix 0.4.14 → 0.4.16

package/dist/index.js

@@ -2795,7 +2795,6 @@ function buildExecApprovalCardEnvelope(payload) {
 var BIZ_CARD_EXTRA_KEY2 = "biz_card";
 var BIZ_CARD_VERSION2 = 1;
 var EGG_INSTALL_STATUS_CARD_TYPE = "egg_install_status";
-var DIRECTIVE_REGEX = /^\s*\[\[egg-install-status\|(.+?)\]\]\s*$/i;
 function normalizeText3(value) {
   return String(value ?? "").replace(/\r\n/g, "\n").trim();
 }
@@ -2806,20 +2805,6 @@ function normalizeStatus(value) {
   }
   return void 0;
 }
-function decodeDirectiveValue(rawValue) {
-  const normalized = rawValue.trim();
-  if (!normalized) {
-    return void 0;
-  }
-  if (!normalized.includes("%")) {
-    return normalized;
-  }
-  try {
-    return decodeURIComponent(normalized);
-  } catch {
-    return normalized;
-  }
-}
 function stripUndefinedFields2(record) {
   const next = {};
   for (const [key, value] of Object.entries(record)) {
@@ -2887,8 +2872,7 @@ function finalizeParsed(parsed) {
   });
   return next;
 }
-function parseStructuredEggInstall(payload) {
-  const channelData = payload.channelData;
+function extractEggInstallRecord(channelData) {
   if (!channelData || typeof channelData !== "object" || Array.isArray(channelData)) {
     return null;
   }
@@ -2900,7 +2884,13 @@ function parseStructuredEggInstall(payload) {
   if (!eggInstall || typeof eggInstall !== "object" || Array.isArray(eggInstall)) {
     return null;
   }
-  const record = eggInstall;
+  return eggInstall;
+}
+function parseStructuredEggInstall(payload) {
+  const record = extractEggInstallRecord(payload.channelData);
+  if (!record) {
+    return null;
+  }
   return finalizeParsed({
     install_id: record.install_id,
     status: record.status,
@@ -2912,46 +2902,38 @@ function parseStructuredEggInstall(payload) {
     error_msg: record.error_msg
   });
 }
-function parseDirectiveEggInstall(payload) {
-  const rawText = String(payload.text ?? "");
-  const match = DIRECTIVE_REGEX.exec(rawText);
-  if (!match) {
+function parseEmbeddedReplyPayloadEggInstall(payload) {
+  const rawText = normalizeText3(payload.text);
+  if (!rawText || !/^[{\[]/.test(rawText)) {
     return null;
   }
-  const body = String(match[1] ?? "").trim();
-  if (!body) {
+  let embeddedReply;
+  try {
+    embeddedReply = JSON.parse(rawText);
+  } catch {
     return null;
   }
-  const fields = /* @__PURE__ */ new Map();
-  for (const segment of body.split("|")) {
-    const normalizedSegment = segment.trim();
-    if (!normalizedSegment) {
-      return null;
-    }
-    const separatorIndex = normalizedSegment.indexOf("=");
-    if (separatorIndex <= 0 || separatorIndex >= normalizedSegment.length - 1) {
-      return null;
-    }
-    const key = normalizedSegment.slice(0, separatorIndex).trim();
-    const decoded = decodeDirectiveValue(normalizedSegment.slice(separatorIndex + 1));
-    if (!key || !decoded) {
-      return null;
-    }
-    fields.set(key, decoded);
+  if (!embeddedReply || typeof embeddedReply !== "object" || Array.isArray(embeddedReply)) {
+    return null;
+  }
+  const record = embeddedReply;
+  const eggInstall = extractEggInstallRecord(record.channelData);
+  if (!eggInstall) {
+    return null;
   }
   return finalizeParsed({
-    install_id: fields.get("install_id"),
-    status: fields.get("status"),
-    step: fields.get("step"),
-    summary: fields.get("summary"),
-    detail_text: fields.get("detail_text"),
-    target_agent_id: fields.get("target_agent_id"),
-    error_code: fields.get("error_code"),
-    error_msg: fields.get("error_msg")
+    install_id: eggInstall.install_id,
+    status: eggInstall.status,
+    step: eggInstall.step,
+    summary: eggInstall.summary ?? record.text,
+    detail_text: eggInstall.detail_text,
+    target_agent_id: eggInstall.target_agent_id,
+    error_code: eggInstall.error_code,
+    error_msg: eggInstall.error_msg
   });
 }
 function buildEggInstallStatusCardEnvelope(payload) {
-  const parsed = parseStructuredEggInstall(payload) ?? parseDirectiveEggInstall(payload);
+  const parsed = parseStructuredEggInstall(payload) ?? parseEmbeddedReplyPayloadEggInstall(payload);
   if (!parsed) {
     return void 0;
   }
@@ -3075,24 +3057,149 @@ function buildExecApprovalResolutionReply(params) {
   };
 }
 
+// src/user-profile-card.ts
+var BIZ_CARD_EXTRA_KEY4 = "biz_card";
+var BIZ_CARD_VERSION4 = 1;
+var USER_PROFILE_CARD_TYPE = "user_profile";
+function normalizeText5(value) {
+  return String(value ?? "").replace(/\r\n/g, "\n").trim();
+}
+function normalizePeerType(value) {
+  if (value === 1 || value === "1") {
+    return 1;
+  }
+  if (value === 2 || value === "2") {
+    return 2;
+  }
+  return void 0;
+}
+function stripUndefinedFields4(record) {
+  const next = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (value !== void 0) {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+function buildFallbackText2(parsed) {
+  const nickname = parsed.nickname.replace(/\s+/g, " ").trim();
+  const compactNickname = nickname.length > 120 ? `${nickname.slice(0, 117)}...` : nickname;
+  return `[Profile Card] ${compactNickname}`;
+}
+function buildExtra2(parsed) {
+  return {
+    [BIZ_CARD_EXTRA_KEY4]: {
+      version: BIZ_CARD_VERSION4,
+      type: USER_PROFILE_CARD_TYPE,
+      payload: stripUndefinedFields4(parsed)
+    },
+    channel_data: {
+      grix: {
+        userProfile: stripUndefinedFields4(parsed)
+      }
+    }
+  };
+}
+function finalizeParsed2(parsed) {
+  const userId = normalizeText5(parsed.user_id);
+  const nickname = normalizeText5(parsed.nickname);
+  const peerType = parsed.peer_type === void 0 ? 1 : normalizePeerType(parsed.peer_type);
+  if (!userId || !nickname || !peerType) {
+    return null;
+  }
+  return stripUndefinedFields4({
+    user_id: userId,
+    peer_type: peerType,
+    nickname,
+    avatar_url: normalizeText5(parsed.avatar_url) || void 0
+  });
+}
+function extractUserProfileRecord(channelData) {
+  if (!channelData || typeof channelData !== "object" || Array.isArray(channelData)) {
+    return null;
+  }
+  const grix = channelData.grix;
+  if (!grix || typeof grix !== "object" || Array.isArray(grix)) {
+    return null;
+  }
+  const userProfile = grix.userProfile;
+  if (!userProfile || typeof userProfile !== "object" || Array.isArray(userProfile)) {
+    return null;
+  }
+  return userProfile;
+}
+function parseStructuredUserProfile(payload) {
+  const record = extractUserProfileRecord(payload.channelData);
+  if (!record) {
+    return null;
+  }
+  return finalizeParsed2({
+    user_id: record.user_id,
+    peer_type: record.peer_type,
+    nickname: record.nickname,
+    avatar_url: record.avatar_url
+  });
+}
+function parseEmbeddedReplyPayloadUserProfile(payload) {
+  const rawText = normalizeText5(payload.text);
+  if (!rawText || !/^[{\[]/.test(rawText)) {
+    return null;
+  }
+  let embeddedReply;
+  try {
+    embeddedReply = JSON.parse(rawText);
+  } catch {
+    return null;
+  }
+  if (!embeddedReply || typeof embeddedReply !== "object" || Array.isArray(embeddedReply)) {
+    return null;
+  }
+  const record = embeddedReply;
+  const userProfile = extractUserProfileRecord(record.channelData);
+  if (!userProfile) {
+    return null;
+  }
+  return finalizeParsed2({
+    user_id: userProfile.user_id,
+    peer_type: userProfile.peer_type,
+    nickname: userProfile.nickname ?? record.text,
+    avatar_url: userProfile.avatar_url
+  });
+}
+function buildUserProfileCardEnvelope(payload) {
+  const parsed = parseStructuredUserProfile(payload) ?? parseEmbeddedReplyPayloadUserProfile(payload);
+  if (!parsed) {
+    return void 0;
+  }
+  return {
+    extra: buildExtra2(parsed),
+    fallbackText: buildFallbackText2(parsed)
+  };
+}
+
 // src/outbound-envelope.ts
+function buildAibotOutboundTextEnvelope(text) {
+  return buildAibotOutboundEnvelope({ text });
+}
 function buildAibotOutboundEnvelope(payload) {
   const execApprovalDiagnostic = diagnoseExecApprovalPayload(payload);
   const execApprovalCard = buildExecApprovalCardEnvelope(payload);
   const execStatusCard = execApprovalCard ? void 0 : buildExecStatusCardEnvelope(payload);
   const eggInstallStatusCard = execApprovalCard || execStatusCard ? void 0 : buildEggInstallStatusCardEnvelope(payload);
-  const envelope = execApprovalCard ?? execStatusCard ?? eggInstallStatusCard;
+  const userProfileCard = execApprovalCard || execStatusCard || eggInstallStatusCard ? void 0 : buildUserProfileCardEnvelope(payload);
+  const envelope = execApprovalCard ?? execStatusCard ?? eggInstallStatusCard ?? userProfileCard;
   return {
     text: envelope?.fallbackText ?? String(payload.text ?? ""),
     extra: envelope?.extra,
-    cardKind: execApprovalCard ? "exec_approval" : execStatusCard ? "exec_status" : eggInstallStatusCard ? "egg_install_status" : void 0,
+    cardKind: execApprovalCard ? "exec_approval" : execStatusCard ? "exec_status" : eggInstallStatusCard ? "egg_install_status" : userProfileCard ? "user_profile" : void 0,
     execApprovalDiagnostic
   };
 }
 
 // src/exec-approval-command.ts
 var COMMAND_REGEX = /^\/approve(?:@[^\s]+)?(?:\s|$)/i;
-var DIRECTIVE_REGEX2 = /\[\[exec-approval-resolution\|(.+?)\]\]/i;
+var DIRECTIVE_REGEX = /\[\[exec-approval-resolution\|(.+?)\]\]/i;
 var DECISION_ALIASES = {
   allow: "allow-once",
   once: "allow-once",
@@ -3106,7 +3213,7 @@ var DECISION_ALIASES = {
   block: "deny"
 };
 var EXEC_APPROVAL_USAGE = "Usage: /approve <id> allow-once|allow-always|deny";
-function decodeDirectiveValue2(rawValue) {
+function decodeDirectiveValue(rawValue) {
   const normalized = rawValue.trim();
   if (!normalized) {
     return void 0;
@@ -3121,7 +3228,7 @@ function decodeDirectiveValue2(rawValue) {
   }
 }
 function parseExecApprovalResolutionDirective(raw) {
-  const match = DIRECTIVE_REGEX2.exec(String(raw ?? ""));
+  const match = DIRECTIVE_REGEX.exec(String(raw ?? ""));
   if (!match) {
     return { matched: false };
   }
@@ -3141,7 +3248,7 @@ function parseExecApprovalResolutionDirective(raw) {
     }
     const key = normalizedSegment.slice(0, separatorIndex).trim();
     const rawValue = normalizedSegment.slice(separatorIndex + 1);
-    const value = decodeDirectiveValue2(rawValue);
+    const value = decodeDirectiveValue(rawValue);
     if (!key || !value) {
       return { matched: true, ok: false, error: EXEC_APPROVAL_USAGE };
     }
@@ -3430,6 +3537,11 @@ function shouldTreatDispatchAsRespondedWithoutVisibleOutput(result) {
   return false;
 }
 
+// src/final-streamed-reply-policy.ts
+function shouldSkipFinalReplyAfterStreamedBlock(params) {
+  return params.kind === "final" && params.streamedTextAlreadyVisible && !params.hasMedia && params.text.length > 0 && !params.hasStructuredCard;
+}
+
 // src/outbound-text-delivery-plan.ts
 function buildAibotTextSendPlan(params) {
   const plan = [];
@@ -3570,6 +3682,87 @@ async function deliverAibotPayload(params) {
   return { sent, firstMessageId };
 }
 
+// src/group-semantics.ts
+function normalizeEventType(value) {
+  return String(value ?? "").trim().toLowerCase();
+}
+function normalizeMentionUserIds(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  const deduped = /* @__PURE__ */ new Set();
+  for (const entry of value) {
+    const normalized = String(entry ?? "").trim();
+    if (normalized) {
+      deduped.add(normalized);
+    }
+  }
+  return [...deduped];
+}
+function resolveGrixInboundSemantics(event) {
+  const eventType = normalizeEventType(event.event_type);
+  const isGroup = Number(event.session_type ?? 0) === 2 || eventType.startsWith("group_");
+  const mentionUserIds = normalizeMentionUserIds(event.mention_user_ids);
+  const hasAnyMention = mentionUserIds.length > 0;
+  const wasMentioned = isGroup && eventType === "group_mention";
+  const mentionsOther = isGroup && hasAnyMention && !wasMentioned;
+  const mustReply = wasMentioned;
+  const allowSilent = isGroup && !mustReply;
+  const allowActions = !isGroup || mustReply;
+  return {
+    isGroup,
+    eventType,
+    wasMentioned,
+    hasAnyMention,
+    mentionsOther,
+    mentionUserIds,
+    mustReply,
+    allowSilent,
+    allowActions
+  };
+}
+function buildGrixGroupSystemPrompt(semantics) {
+  if (!semantics.isGroup) {
+    return void 0;
+  }
+  if (semantics.wasMentioned) {
+    return [
+      "This group turn explicitly targeted you.",
+      "You must reply or take the requested action when appropriate.",
+      "Do not return NO_REPLY for this turn."
+    ].join(" ");
+  }
+  if (semantics.mentionsOther) {
+    return [
+      "This group turn explicitly targeted someone else, not you.",
+      "You may reply only if you add clear value.",
+      "Otherwise return NO_REPLY.",
+      "Do not take action unless the task is clearly yours."
+    ].join(" ");
+  }
+  return [
+    "This group turn is visible context, not an explicit mention for you.",
+    "Reply only if it clearly helps the conversation.",
+    "Otherwise return NO_REPLY.",
+    "Do not take action unless the task is clearly yours."
+  ].join(" ");
+}
+function resolveGrixMentionFallbackText() {
+  return "I'm here.";
+}
+function resolveGrixDispatchResolution(params) {
+  if (params.visibleOutputSent || params.eventResultReported) {
+    return {
+      shouldCompleteSilently: false,
+      shouldSendMentionFallback: false
+    };
+  }
+  return {
+    shouldCompleteSilently: params.semantics.allowSilent,
+    shouldSendMentionFallback: params.semantics.mustReply
+  };
+}
+
 // src/monitor.ts
 var activeMonitorClients = /* @__PURE__ */ new Map();
 function registerActiveMonitor(accountId, client) {
@@ -3847,8 +4040,10 @@ async function processEvent(params) {
   const quotedMessageId = normalizeNumericMessageId(event.quoted_message_id);
   const bodyForAgent = buildBodyWithQuotedReplyId(rawBody, quotedMessageId);
   const senderId = toStringId2(event.sender_id);
-  const isGroup = Number(event.session_type ?? 0) === 2 || String(event.event_type ?? "").startsWith("group_");
+  const semantics = resolveGrixInboundSemantics(event);
+  const isGroup = semantics.isGroup;
   const chatType = isGroup ? "group" : "direct";
+  const groupSystemPrompt = buildGrixGroupSystemPrompt(semantics);
   const createdAt = toTimestampMs(event.created_at);
   const baseLogContext = buildEventLogContext({
     eventId,
@@ -3884,7 +4079,7 @@ async function processEvent(params) {
     return;
   }
   runtime2.log(
-    `[grix:${account.accountId}] inbound event ${baseLogContext} chatType=${chatType} bodyLen=${rawBody.length} quotedMessageId=${quotedMessageId || "-"}`
+    `[grix:${account.accountId}] inbound event ${baseLogContext} chatType=${chatType} eventType=${semantics.eventType || "-"} wasMentioned=${semantics.wasMentioned ? "true" : "false"} mentionsOther=${semantics.mentionsOther ? "true" : "false"} bodyLen=${rawBody.length} quotedMessageId=${quotedMessageId || "-"}`
   );
   let inboundEventAccepted = false;
   const commandOutcome = await handleExecApprovalCommand({
@@ -3994,6 +4189,7 @@ async function processEvent(params) {
       SessionKey: route.sessionKey,
       AccountId: route.accountId,
       ChatType: chatType,
+      GroupSystemPrompt: groupSystemPrompt,
       ConversationLabel: fromLabel,
       SenderName: senderId || void 0,
       SenderId: senderId || void 0,
@@ -4004,6 +4200,7 @@ async function processEvent(params) {
       // This field carries the inbound quoted message id from end user (event.quoted_message_id).
       // It is not the outbound reply anchor used when plugin sends replies back to Aibot.
       ReplyToMessageSid: quotedMessageId,
+      WasMentioned: isGroup ? semantics.wasMentioned : void 0,
       OriginatingChannel: "grix",
       OriginatingTo: to
     });
@@ -4216,6 +4413,7 @@ async function processEvent(params) {
                 outboundCounter
               });
               const isStreamBlock = info.kind === "block" && !guardedText && !hasMedia && text.length > 0;
+              const finalOutboundEnvelope = info.kind === "final" ? buildAibotOutboundEnvelope(normalizedPayload) : void 0;
               if (!isStreamBlock) {
                 runtime2.log(
                   `[grix:${account.accountId}] deliver ${deliverContext} kind=${info.kind} textLen=${text.length} hasMedia=${hasMedia} streamedBefore=${streamedTextAlreadyVisible}`
@@ -4261,7 +4459,13 @@ async function processEvent(params) {
                 return;
               }
               await finishStreamIfNeeded();
-              if (info.kind === "final" && streamedTextAlreadyVisible && !hasMedia && text) {
+              if (shouldSkipFinalReplyAfterStreamedBlock({
+                kind: info.kind,
+                streamedTextAlreadyVisible,
+                hasMedia,
+                text,
+                hasStructuredCard: Boolean(finalOutboundEnvelope?.cardKind)
+              })) {
                 runtime2.log(
                   `[grix:${account.accountId}] skip final text after streamed block ${deliverContext} textLen=${text.length}`
                 );
@@ -4357,6 +4561,49 @@ async function processEvent(params) {
             markVisibleOutputSent();
           }
         }
+        const dispatchResolution = resolveGrixDispatchResolution({
+          semantics,
+          visibleOutputSent,
+          eventResultReported
+        });
+        if (dispatchResolution.shouldCompleteSilently) {
+          runtime2.log(
+            `[grix:${account.accountId}] group dispatch completed silently ${baseLogContext} attempt=${attemptLabel} wasMentioned=${semantics.wasMentioned ? "true" : "false"}`
+          );
+          reportEventResult("responded");
+        }
+        if (dispatchResolution.shouldSendMentionFallback) {
+          outboundCounter++;
+          const stableClientMsgId = `reply_${messageSid}_${outboundCounter}`;
+          runtime2.log(
+            `[grix:${account.accountId}] explicit mention fallback reply ${buildEventLogContext({
+              eventId,
+              sessionId,
+              messageSid,
+              clientMsgId: stableClientMsgId,
+              outboundCounter
+            })}`
+          );
+          const didSendFallback = await deliverAibotMessage({
+            payload: {
+              text: resolveGrixMentionFallbackText()
+            },
+            client,
+            account,
+            sessionId,
+            abortSignal: runAbortController.signal,
+            eventId,
+            quotedMessageId: outboundQuotedMessageId,
+            runtime: runtime2,
+            statusSink,
+            stableClientMsgId,
+            tableMode
+          });
+          attemptHasOutbound = attemptHasOutbound || didSendFallback;
+          if (didSendFallback) {
+            markVisibleOutputSent();
+          }
+        }
         break;
       }
       if (!visibleOutputSent && !eventResultReported) {
@@ -4579,6 +4826,26 @@ function applySetupAccountConfig(params) {
   };
 }
 
+// src/group-adapter.ts
+function resolveGrixGroupRequireMention() {
+  return false;
+}
+function resolveGrixGroupIntroHint() {
+  return [
+    "All Grix group messages are visible to you.",
+    "If WasMentioned is true, you are the primary addressee and should respond.",
+    "If WasMentioned is false, reply only when you add clear value; otherwise use NO_REPLY."
+  ].join(" ");
+}
+
+// src/group-tool-policy.ts
+var GROUP_DEFAULT_DENY = ["message"];
+function resolveGrixGroupToolPolicy() {
+  return {
+    deny: [...GROUP_DEFAULT_DENY]
+  };
+}
+
 // src/channel.ts
 var meta = {
   id: "grix",
@@ -4795,6 +5062,11 @@ var aibotPlugin = {
       hasRepliedRef
     })
   },
+  groups: {
+    resolveRequireMention: () => resolveGrixGroupRequireMention(),
+    resolveGroupIntroHint: () => resolveGrixGroupIntroHint(),
+    resolveToolPolicy: () => resolveGrixGroupToolPolicy()
+  },
   agentPrompt: {
     messageToolHints: () => [
       "- Grix `action=unsend` is a silent cleanup action: unsend the target `messageId`, unsend the recall command message when applicable, then end with `NO_REPLY` and do not send any confirmation text. Omit `sessionId`/`to` only when targeting the current Grix chat."
@@ -4827,14 +5099,16 @@ var aibotPlugin = {
       }
       const sessionId = resolvedTarget.sessionId;
       const quotedMessageId = normalizeQuotedMessageId(replyToId);
+      const envelope = buildAibotOutboundTextEnvelope(text);
       logAibotOutboundAdapter(
-        `sendText accountId=${account.accountId} rawTarget=${rawTarget} normalizedTarget=${resolvedTarget.normalizedTarget} resolvedSessionId=${sessionId} resolveSource=${resolvedTarget.resolveSource} textLen=${text.length} quotedMessageId=${quotedMessageId ?? "-"}`
+        `sendText accountId=${account.accountId} rawTarget=${rawTarget} normalizedTarget=${resolvedTarget.normalizedTarget} resolvedSessionId=${sessionId} resolveSource=${resolvedTarget.resolveSource} textLen=${envelope.text.length} quotedMessageId=${quotedMessageId ?? "-"} cardKind=${envelope.cardKind ?? "none"}`
       );
-      const ack = await client.sendText(sessionId, text, {
-        quotedMessageId
+      const ack = await client.sendText(sessionId, envelope.text, {
+        quotedMessageId,
+        extra: envelope.extra
       });
       logAibotOutboundAdapter(
-        `sendText ack accountId=${account.accountId} resolvedSessionId=${sessionId} messageId=${String(ack.msg_id ?? ack.client_msg_id ?? "-")}`
+        `sendText ack accountId=${account.accountId} resolvedSessionId=${sessionId} messageId=${String(ack.msg_id ?? ack.client_msg_id ?? "-")} cardKind=${envelope.cardKind ?? "none"}`
       );
       return {
         channel: "grix",
@@ -6111,7 +6385,8 @@ async function createGrixApiAgent(params) {
         agentId,
         apiKeyPlaceholder: "<NEW_AGENT_API_KEY>"
       })}\``,
-      "Restart the gateway after adding the channel: `openclaw gateway restart`."
+      "After binding the channel, apply agents/bindings/tools changes through `openclaw config set` or the bundled `grix_agent_bind.py configure-local-openclaw --apply` flow.",
+      "Do not run `openclaw gateway restart` during an active install chat. Prefer a guarded apply flow that temporarily uses `gateway.reload.mode=hot` so the current conversation is not interrupted."
     ] : []
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhf-openclaw/grix",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "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

@@ -30,7 +30,8 @@ scripts/grix_agent_bind.py configure-local-openclaw \
   --apply
 ```
 
-2. 可选执行检查：
+2. 绑定脚本会通过 `openclaw config set` 落配置，并在写入前临时把 `gateway.reload.mode` 切到 `hot`，避免当前安装对话被自动重启打断；不要在这条安装对话里追加 `openclaw gateway restart`。
+3. 执行完后必须再做一次检查：
 
 ```bash
 scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>
@@ -51,6 +52,7 @@ scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>
 2. 若缺失或为空，说明主通道还没完成，不做本模式，立刻切回 `grix-register`。
 3. 若已存在，再调用 `grix_agent_admin` 创建远端 agent（仅一次，不自动重试）。
 4. 创建成功后，执行本地绑定命令（同 Mode A）。
+5. 整个 `create-and-bind` 流程里不要执行 `openclaw gateway restart`；优先让绑定脚本用 `gateway.reload.mode=hot` 保护当前会话不被自动重启打断。
 
 ## Guardrails（两种模式都适用）
 
@@ -59,6 +61,8 @@ scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>
 3. 远端创建（Mode B）视为非幂等，不确认不自动重试。
 4. 完整 `api_key` 仅一次性回传，不要重复明文回显。
 5. 本地 `--apply` 没成功前，不得宣称配置完成。
+6. 安装私聊进行中时，禁止手工修改 `openclaw.json` 后再执行 `openclaw gateway restart`。
+7. 如果绑定脚本输出 `runtime_reload.restart_hint_detected=true`，说明当前 OpenClaw 版本仍提示“需要重启才生效”；此时不要自动重启，只能明确告诉用户“配置已写入，等待空闲时手动重启生效”。
 
 ## Error Handling Rules
 

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

@@ -79,15 +79,20 @@ After `code=0` (or when using `bind-local` mode), continue with local OpenClaw b
 
 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`
-2. optionally run inspect after apply when you need state verification:
+2. inspect after apply and use the result as the success gate:
    - `scripts/grix_agent_bind.py inspect-local-openclaw --agent-name <agent_name>`
+3. read `runtime_reload` from the apply result:
+   - `temporary_hot_mode=true` means the script temporarily guarded the write with `gateway.reload.mode=hot`
+   - `restart_hint_detected=true` means the running OpenClaw build still wants a later manual restart before the new config becomes live
 
-Local apply writes:
+Local apply writes and validates:
 
 1. `agents.list` entry
 2. `channels.grix.accounts.<agent_name>` entry
 3. `bindings` route for `channel=grix`
-4. required tools config and gateway restart
+4. required tools config
+5. the script temporarily guards the apply with `gateway.reload.mode=hot` so the install chat is not interrupted by auto-restart
+6. if `restart_hint_detected=true`, do not run `openclaw gateway restart` inside the install chat; tell the user the config is staged and needs a later manual restart to become live
 
 ## bind-local Input Contract
 

package/skills/grix-admin/scripts/grix_agent_bind.py

@@ -5,7 +5,6 @@ import os
 import shlex
 import subprocess
 import sys
-import uuid
 
 
 DEFAULT_OPENCLAW_CONFIG_PATH = "~/.openclaw/openclaw.json"
@@ -55,19 +54,6 @@ def load_json_file(path: str):
     return json.loads(raw)
 
 
-def write_json_file_with_backup(path: str, payload):
-    os.makedirs(os.path.dirname(path), exist_ok=True)
-    backup_path = ""
-    if os.path.exists(path):
-        backup_path = f"{path}.bak.{uuid.uuid4().hex[:8]}"
-        with open(path, "rb") as src, open(backup_path, "wb") as dst:
-            dst.write(src.read())
-    with open(path, "w", encoding="utf-8") as handle:
-        json.dump(payload, handle, ensure_ascii=False, indent=2)
-        handle.write("\n")
-    return backup_path
-
-
 def normalize_string_list(values):
     if not isinstance(values, list):
         return []
@@ -100,14 +86,23 @@ def redact_channel_account(account):
     return payload
 
 
+def redact_accounts_map(accounts):
+    if not isinstance(accounts, dict):
+        return {}
+    return {
+        str(key): redact_channel_account(value if isinstance(value, dict) else {})
+        for key, value in accounts.items()
+    }
+
+
 def shell_command(cmd):
     return " ".join(shlex.quote(part) for part in cmd)
 
 
-def run_command_capture(cmd):
-    proc = subprocess.run(cmd, capture_output=True, text=True)
+def run_command_capture(cmd, env=None, display_command=None):
+    proc = subprocess.run(cmd, capture_output=True, text=True, env=env)
     return {
-        "command": shell_command(cmd),
+        "command": display_command or shell_command(cmd),
         "returncode": proc.returncode,
         "stdout": proc.stdout.strip(),
         "stderr": proc.stderr.strip(),
@@ -122,8 +117,28 @@ def build_openclaw_base_cmd(args):
     return base_cmd
 
 
-def build_gateway_restart_command(args):
-    return build_openclaw_base_cmd(args) + ["gateway", "restart"]
+def build_openclaw_env(args):
+    env = os.environ.copy()
+    env["OPENCLAW_CONFIG_PATH"] = resolve_config_path(args)
+    return env
+
+
+def build_openclaw_config_set_command(args, path: str, value):
+    return build_openclaw_base_cmd(args) + [
+        "config",
+        "set",
+        path,
+        json.dumps(value, ensure_ascii=False),
+        "--strict-json",
+    ]
+
+
+def build_openclaw_config_validate_command(args):
+    return build_openclaw_base_cmd(args) + ["config", "validate"]
+
+
+def build_openclaw_config_unset_command(args, path: str):
+    return build_openclaw_base_cmd(args) + ["config", "unset", path]
 
 
 def ensure_agent_entry(cfg, target_agent):
@@ -257,6 +272,172 @@ def ensure_required_tools(cfg):
     return next_cfg, changed
 
 
+def resolve_reload_mode(cfg):
+    gateway = cfg.get("gateway") if isinstance(cfg, dict) else {}
+    if not isinstance(gateway, dict):
+        return ""
+    reload_cfg = gateway.get("reload")
+    if not isinstance(reload_cfg, dict):
+        return ""
+    return str(reload_cfg.get("mode", "")).strip()
+
+
+def build_local_config_operations(next_cfg, change_flags, agent_name: str, target_account):
+    operations = []
+
+    if bool(change_flags.get("channel_account_updated")):
+        channels = next_cfg.get("channels") if isinstance(next_cfg, dict) else {}
+        grix = channels.get("grix") if isinstance(channels, dict) else {}
+        accounts = grix.get("accounts") if isinstance(grix, dict) else {}
+        operations.append(
+            {
+                "path": "channels.grix.enabled",
+                "value": bool(grix.get("enabled", True)),
+            }
+        )
+        operations.append(
+            {
+                "path": "channels.grix.accounts",
+                "value": dict(accounts or {}),
+                "display_value": redact_accounts_map(accounts or {}),
+            }
+        )
+
+    if bool(change_flags.get("agent_entry_updated")):
+        agents = next_cfg.get("agents") if isinstance(next_cfg, dict) else {}
+        operations.append(
+            {
+                "path": "agents.list",
+                "value": list(agents.get("list") or []),
+            }
+        )
+
+    if bool(change_flags.get("route_binding_updated")):
+        operations.append(
+            {
+                "path": "bindings",
+                "value": list(next_cfg.get("bindings") or []),
+            }
+        )
+
+    if bool(change_flags.get("tools_updated")):
+        tools = next_cfg.get("tools") if isinstance(next_cfg, dict) else {}
+        if not isinstance(tools, dict):
+            tools = {}
+        sessions = tools.get("sessions") if isinstance(tools.get("sessions"), dict) else {}
+        operations.extend(
+            [
+                {
+                    "path": "tools.profile",
+                    "value": str(tools.get("profile", "")).strip(),
+                },
+                {
+                    "path": "tools.alsoAllow",
+                    "value": normalize_string_list(tools.get("alsoAllow")),
+                },
+                {
+                    "path": "tools.sessions.visibility",
+                    "value": str(sessions.get("visibility", "")).strip(),
+                },
+            ]
+        )
+
+    return operations
+
+
+def wrap_with_hot_reload_guard(cfg, operations):
+    if not operations:
+        return operations, {"before": resolve_reload_mode(cfg), "temporary_hot_mode": False}
+
+    previous_mode = resolve_reload_mode(cfg)
+    if previous_mode == "hot":
+        return operations, {"before": previous_mode, "temporary_hot_mode": False}
+
+    guarded_operations = [
+        {
+            "kind": "set",
+            "path": "gateway.reload.mode",
+            "value": "hot",
+        }
+    ]
+    guarded_operations.extend(operations)
+    if previous_mode:
+        guarded_operations.append(
+            {
+                "kind": "set",
+                "path": "gateway.reload.mode",
+                "value": previous_mode,
+            }
+        )
+    else:
+        guarded_operations.append(
+            {
+                "kind": "unset",
+                "path": "gateway.reload.mode",
+            }
+        )
+    return guarded_operations, {"before": previous_mode, "temporary_hot_mode": True}
+
+
+def build_local_config_plan(args, operations):
+    plan = []
+    for operation in operations:
+        kind = str(operation.get("kind") or "set").strip() or "set"
+        path = str(operation.get("path") or "").strip()
+        if kind == "unset":
+            command = build_openclaw_config_unset_command(args, path)
+            plan.append(shell_command(command))
+            continue
+        display_value = operation.get("display_value", operation.get("value"))
+        command = build_openclaw_config_set_command(args, path, display_value)
+        plan.append(shell_command(command))
+    plan.append(shell_command(build_openclaw_config_validate_command(args)))
+    return plan
+
+
+def apply_local_config_operations(args, operations):
+    env = build_openclaw_env(args)
+    command_results = []
+
+    for operation in operations:
+        kind = str(operation.get("kind") or "set").strip() or "set"
+        path = str(operation.get("path") or "").strip()
+        if kind == "unset":
+            command = build_openclaw_config_unset_command(args, path)
+            display_command = shell_command(command)
+            result = run_command_capture(command, env=env, display_command=display_command)
+            command_results.append(result)
+            if result["returncode"] != 0:
+                raise BindError(
+                    f"openclaw config unset failed for {path}",
+                    payload={"command_results": command_results},
+                )
+            continue
+
+        value = operation.get("value")
+        display_value = operation.get("display_value", value)
+        command = build_openclaw_config_set_command(args, path, value)
+        display_command = shell_command(build_openclaw_config_set_command(args, path, display_value))
+        result = run_command_capture(command, env=env, display_command=display_command)
+        command_results.append(result)
+        if result["returncode"] != 0:
+            raise BindError(
+                f"openclaw config set failed for {path}",
+                payload={"command_results": command_results},
+            )
+
+    validate_command = build_openclaw_config_validate_command(args)
+    validate_result = run_command_capture(validate_command, env=env)
+    command_results.append(validate_result)
+    if validate_result["returncode"] != 0:
+        raise BindError(
+            "openclaw config validate failed",
+            payload={"command_results": command_results},
+        )
+
+    return command_results
+
+
 def resolve_default_model(cfg, current_agent):
     if isinstance(current_agent, dict):
         model = str(current_agent.get("model", "")).strip()
@@ -449,6 +630,10 @@ def handle_configure_local(args):
         change_flags["tools_updated"] = changed
 
     needs_update = any(bool(value) for value in change_flags.values())
+    base_apply_operations = build_local_config_operations(
+        next_cfg, change_flags, agent_name, target_account
+    )
+    apply_operations, reload_guard = wrap_with_hot_reload_guard(cfg, base_apply_operations)
 
     payload = {
         "ok": True,
@@ -483,23 +668,33 @@ def handle_configure_local(args):
                 },
             },
         },
-        "planned_apply_commands": [] if bool(args.skip_gateway_restart) else [shell_command(build_gateway_restart_command(args))],
+        "planned_apply_commands": build_local_config_plan(args, apply_operations),
+        "runtime_reload": {
+            "mode": "guarded_hot_reload",
+            "previous_mode": reload_guard.get("before") or "default",
+            "temporary_hot_mode": bool(reload_guard.get("temporary_hot_mode")),
+            "summary": "The script temporarily switches gateway.reload.mode to hot while applying config so the active install chat is not interrupted by an automatic restart.",
+        },
     }
 
     if args.apply:
-        backup_path = ""
-        if needs_update:
-            backup_path = write_json_file_with_backup(config_path, next_cfg)
         created_paths = []
         created_paths.extend(build_workspace_files(workspace, agent_name))
         os.makedirs(agent_dir, exist_ok=True)
 
         command_results = []
-        if not bool(args.skip_gateway_restart):
-            command_results.append(run_command_capture(build_gateway_restart_command(args)))
+        if needs_update:
+            command_results = apply_local_config_operations(args, apply_operations)
+        else:
+            command_results = [
+                run_command_capture(
+                    build_openclaw_config_validate_command(args),
+                    env=build_openclaw_env(args),
+                )
+            ]
             if command_results[-1]["returncode"] != 0:
                 raise BindError(
-                    "openclaw gateway restart failed",
+                    "openclaw config validate failed",
                     payload={"command_results": command_results},
                 )
 
@@ -507,10 +702,15 @@ def handle_configure_local(args):
         applied_state = extract_current_state(applied_cfg, agent_name)
         payload["config_write"] = {
             "changed": needs_update,
-            "backup_path": backup_path,
+            "mode": "openclaw config set",
+            "applied_paths": [item.get("path") for item in apply_operations],
         }
         payload["created_workspace_files"] = created_paths
         payload["command_results"] = command_results
+        payload["runtime_reload"]["restart_hint_detected"] = any(
+            "restart the gateway to apply" in f"{item.get('stdout', '')} {item.get('stderr', '')}".lower()
+            for item in command_results
+        )
         payload["applied_state"] = {
             "agent_entry": (applied_state or {}).get("agent_entry"),
             "channel_account": redact_channel_account((applied_state or {}).get("channel_account") or {}),
@@ -550,7 +750,6 @@ def build_parser():
     configure_local.add_argument("--workspace", default="")
     configure_local.add_argument("--agent-dir", default="")
     configure_local.add_argument("--skip-tools-update", action="store_true")
-    configure_local.add_argument("--skip-gateway-restart", action="store_true")
     configure_local.add_argument("--apply", action="store_true")
     configure_local.set_defaults(handler=handle_configure_local)
 

package/skills/grix-egg/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grix-egg
-description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 OpenClaw agent 收到包含 install_id、egg、install、main_agent 的安装上下文时，负责与用户多轮确认、执行 persona.zip 到 OpenClaw agent 或 skill.zip 到 Claude agent 的正规安装流程，并在当前私聊里持续回报进度、失败原因和最终结果。
+description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 OpenClaw agent 收到包含 install_id、egg、install、main_agent 的安装上下文时，按 install.route 指定的路线执行安装：把 persona/openclaw 包安装到 OpenClaw agent，或把 skill.zip 安装到 Claude agent，并在当前私聊里持续回报进度、失败原因和最终结果。
 ---
 
 # Egg Install
@@ -9,24 +9,34 @@ description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 O
 
 这类会话通常会先收到一条系统代发的安装请求，正文里会带一个 JSON 上下文块，至少包含：
 
-- `install_id` — 安装单唯一 ID，所有状态指令必须使用原值
+- `install_id` — 安装单唯一 ID，所有状态消息必须使用原值
 - `egg` — egg 包标识，格式为 `<name>@<version>` 或带完整下载 URL 的对象
-- `install` — 安装模式，枚举值：`create_new`（新建目标 agent）或 `existing_agent`（安装到已有 agent）
+- `install.mode` — 安装模式，枚举值：`create_new`（新建目标 agent）或 `existing_agent`（安装到已有 agent）
+- `install.route` — 当前实际路线，优先使用它判断要走哪条分支。当前可见值：
+  - `openclaw_create_new`
+  - `openclaw_existing`
+  - `claude_existing`
+- `install.target_client_type` — 本次目标类型，通常为 `openclaw` 或 `claude`
+- `install.artifact_package` — 本次应安装的包类型，通常为 `persona_zip` 或 `skill_zip`
+- `install.suggested_agent_name` — `openclaw_create_new` 时优先使用的默认短名字；若缺失，再按 egg 标题或 egg ID 自行取一个简短名字继续，不要回头追问用户命名和用途
 - `main_agent` — 发起安装的主 OpenClaw agent ID，安装完成后如需通知或回调，使用该 ID
 
 你的职责不是返回隐藏协议结果，而是直接在当前私聊里把安装流程做完。
 
 ## 工作方式
 
-1. 先读完整个 JSON 上下文，确认 egg、版本、安装模式和目标类型。
-2. 在真正动手前，先在当前私聊里和用户确认关键目标。
-3. `create_new` 时，先确认新 agent 的命名和用途，再继续创建。
-4. `existing_agent` 时，只能操作上下文里指定的目标 agent，不要私自换目标。
+1. 先读完整个 JSON 上下文，优先确认 `install.route`、`install.target_client_type`、`install.artifact_package`。
+2. 默认直接按上下文执行；只有缺少关键信息、上下文互相冲突或执行被阻塞时，才在当前私聊里向用户确认。
+3. `openclaw_create_new` 时，优先使用 `install.suggested_agent_name` 作为新 OpenClaw agent 的默认短名字；若缺失，再按 egg 标题或 egg ID 自行取一个简短名字继续创建，不要回头追问用户命名和用途。
+4. `openclaw_existing` / `claude_existing` 时，只能操作上下文里指定的目标 agent，不要私自换目标；如果目标已经明确，就直接继续，不要重复确认。
 5. 安装过程中，每完成一个关键动作就用自然语言回报一次进度。
-6. 在"包下载完成"和"安装内容落位完成待校验"两个节点，各额外发送一条 `status=running` 的**独立安装状态指令消息**。
-7. 最终成功或失败时，必须发送一条 `status=success` 或 `status=failed` 的**独立安装状态指令消息**。
-8. 出错时，直接说明失败点、影响和下一步建议，不要模糊带过。
-9. 最终明确告诉用户：装到了哪个 agent、结果成功还是失败、后续是否还要继续操作。
+6. `openclaw_create_new` 路线在"远端 agent 创建完成"后，必须额外发送一条 `status=running`、`step=agent_created` 的**独立结构化安装状态消息**。
+7. 在"包下载完成"和"安装内容落位完成待校验"两个节点，各额外发送一条 `status=running` 的**独立结构化安装状态消息**。
+8. 最终成功或失败时，必须发送一条 `status=success` 或 `status=failed` 的**独立结构化安装状态消息**。
+9. 安装成功后，必须再单独发送一条目标 agent 的**结构化资料卡消息**，并且 `peer_type=2`。
+10. 发送完资料卡后，再发一条普通文字，明确告诉用户可以点开资料卡查看 agent 资料，并从资料页继续与它对话。
+11. 出错时，直接说明失败点、影响和下一步建议，不要模糊带过。
+12. 最终明确告诉用户：装到了哪个 agent、结果成功还是失败、后续是否还要继续操作。
 
 ## 绝对规则
 
@@ -36,37 +46,62 @@ description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 O
 - 所有远端 API 通讯都必须走统一工具入口：`grix_query` / `grix_group` / `grix_agent_admin`，禁止在对话里自行发 HTTP 请求。
 - 禁止使用 `curl`、`fetch`、`axios` 或临时脚本直连 `/v1/agent-api`。
 - 单个业务动作只调用一次对应工具，失败后先说明原因，不要静默重试。
-- `persona.zip` 只能面向 OpenClaw 目标。
-- `skill.zip` 只能面向 Claude 目标。
+- 必须以 `install.route` 为准执行，不要自己重新选路线。
+- `openclaw_create_new` / `openclaw_existing` 只能安装 persona/openclaw 包。
+- `claude_existing` 只能安装 skill.zip。
 - 不要自动新建 Claude 目标 agent。
 - 没完成校验前，绝不能宣称安装成功。
 - 如果新建目标后又失败了，能安全回滚就先回滚；不能回滚就如实告诉用户当前残留状态。
-- 最终成功或失败时，必须发送一条独立的 `egg-install-status` 指令消息。
-- 状态指令消息必须单独发送，不要和自然语言解释混在同一条里。
-- 用户拒绝确认或主动取消时，必须发送 `status=failed`、`error_code=user_cancelled` 的状态指令后再结束。
+- 上下文已经给出 `install.target_agent_id` 或 `install.suggested_agent_name` 时，直接继续执行，不要再向用户确认目标、命名或用途；只有信息缺失、冲突或执行阻塞时才提问。
+- 安装私聊进行中时，禁止执行 `openclaw gateway restart`；本流程涉及的 `channels.*`、`agents`、`bindings`、`tools` 配置必须先切到 `gateway.reload.mode=hot` 再写入，避免自动重启打断当前任务。
+- 最终成功或失败时，必须发送一条独立的结构化安装状态消息。
+- 安装成功后，必须按顺序继续发送：目标 agent 的结构化资料卡消息，然后再发一条普通文字的下一步指引。
+- 结构化安装状态消息必须单独发送，不要和自然语言解释混在同一条里。
+- 用户拒绝确认或主动取消时，必须发送 `status=failed`、`error_code=user_cancelled` 的结构化状态消息后再结束。
 
-## 安装状态指令
+## 安装状态消息（OpenClaw ReplyPayload 风格）
 
-server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败"，你必须发送这类单行消息：
+server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败"，你必须单独发送一条**单行 JSON**，格式参考 OpenClaw 的 ReplyPayload：
 
-```text
-[[egg-install-status|install_id=<INSTALL_ID>|status=<running|success|failed>|step=<STEP>|summary=<URI_ENCODED_SUMMARY>]]
+```json
+{"text":"<给用户看的摘要>","channelData":{"grix":{"eggInstall":{"install_id":"<INSTALL_ID>","status":"<running|success|failed>","step":"<STEP>","summary":"<与 text 一致或更精确的摘要>"}}}}
 ```
 
 常用可选字段：
 
-- `target_agent_id=<AGENT_ID>`：成功时尽量带上，尤其是 `create_new`。
-- `detail_text=<URI_ENCODED_DETAIL>`：补充更长说明。
-- `error_code=<ERROR_CODE>`：失败时建议带上。
-- `error_msg=<URI_ENCODED_ERROR_MSG>`：失败时建议带上。
+- `target_agent_id`：成功时尽量带上，尤其是 `create_new`。
+- `detail_text`：补充更长说明。
+- `error_code`：失败时建议带上。
+- `error_msg`：失败时建议带上。
 
 规则：
 
 1. `install_id` 必须使用上下文里的原值。
 2. `status` 只能是 `running`、`success`、`failed`。
-3. `summary`、`detail_text`、`error_msg` 如果有空格、中文或特殊字符，按 URI component 编码。
-4. 这条指令只负责状态收口；如果要跟用户解释原因，另发一条正常文字消息。
-5. `create_new` 成功时，必须尽量带 `target_agent_id`，否则 server 可能无法通过最终校验。
+3. `text` 必须是给用户看的简短摘要；`summary` 应与 `text` 一致，或在不冲突的前提下更精确。
+4. 不要做 URI 编码；直接输出合法 JSON 字符串。
+5. 这条消息只负责状态收口；如果要跟用户解释原因，另发一条正常文字消息。
+6. 顶层只放 `text` 和 `channelData`，不要自己拼前端内部 `biz_card`。
+7. 这条 JSON 必须单独发送，不要前后夹带自然语言。
+8. `openclaw_create_new` 成功时，必须尽量带 `target_agent_id`，否则 server 可能无法通过最终校验。
+9. 如果上下文缺少 `install.route` 但仍有 `install.mode` 和目标 agent 信息，先按上下文能明确推出的路线执行；若仍有歧义，先在当前私聊里确认，再继续。
+
+## Agent 资料卡消息（OpenClaw ReplyPayload 风格）
+
+安装成功后，必须再单独发送一条 agent 资料卡消息，格式如下：
+
+```json
+{"text":"查看 Agent 资料","channelData":{"grix":{"userProfile":{"user_id":"<TARGET_AGENT_ID>","peer_type":2,"nickname":"<AGENT_NAME>","avatar_url":"<可选>"}}}}
+```
+
+规则：
+
+1. `user_id` 必须使用最终目标 agent 的 ID。
+2. `peer_type` 必须固定为 `2`。
+3. `nickname` 必须使用目标 agent 的显示名称。
+4. `avatar_url` 有就带，没有可以省略。
+5. 这条 JSON 也必须单独发送，不要和解释文字混在一起。
+6. 发完资料卡后，再补一条普通文字，告诉用户可以点开资料卡查看资料，并从资料页继续与该 agent 对话。
 
 ## 统一 API 请求机制
 
@@ -84,33 +119,41 @@ server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败
 
 ## 推荐流程
 
-### `persona.zip` -> OpenClaw
-
-1. 读取上下文，确认是 `create_new` 还是 `existing_agent`。
-2. 和用户确认目标 agent 或新 agent 命名；**用户拒绝则发 `failed/user_cancelled` 指令后结束**。
-3. 如果需要新建远端 API agent，用 `grix_agent_admin` 创建。
-4. 用 OpenClaw 正规步骤准备本地目标目录和配置。
-5. 下载 egg 包，并校验 hash / manifest（如果上下文提供）。
-6. 发送 `status=running`、`step=downloaded` 状态指令。
-7. 安装 persona 内容。
-8. 发送 `status=running`、`step=installed` 状态指令。
-9. 按需刷新或重启本地运行时。
-10. 校验目标 agent 仍然可用。
-    - 校验失败 → 尝试回滚（含步骤3新建的远端 agent），无法回滚则如实告知残留状态 → 发 `failed` 指令后结束。
-11. 发送 `status=success` 状态指令（带 `target_agent_id`），再向用户汇报完成。
-
-### `skill.zip` -> Claude
-
-1. 确认上下文指定的 Claude 目标 agent 存在；**不存在则发 `failed/target_not_found` 指令后结束**。
-2. 和用户确认目标 agent；**用户拒绝则发 `failed/user_cancelled` 指令后结束**。
+### `openclaw_create_new` / `openclaw_existing`
+
+1. 读取上下文，确认 route 是 `openclaw_create_new` 还是 `openclaw_existing`。
+2. 如果 route=`openclaw_create_new`，直接使用 `install.suggested_agent_name` 作为默认短名字；若缺失，再按 egg 标题或 egg ID 自行取一个简短名字继续。只有名字或目标信息真的缺失、冲突或执行被阻塞时，才向用户确认；**用户主动取消时发 `failed/user_cancelled` 结构化状态消息后结束**。
+3. 如果 route=`openclaw_existing`，直接使用 `install.target_agent_id` 指定的目标 agent 继续，不要重复确认目标。
+4. 如果 route=`openclaw_create_new`，需要新建远端 API agent，用 `grix_agent_admin` 创建。
+5. 如果 route=`openclaw_create_new` 且远端 agent 已创建成功，立即发送 `status=running`、`step=agent_created` 结构化状态消息。
+6. 用 OpenClaw 正规步骤准备本地目标目录和配置。
+7. 下载 persona/openclaw 包，并校验 hash / manifest（如果上下文提供）。
+8. 发送 `status=running`、`step=downloaded` 结构化状态消息。
+9. 安装 persona/openclaw 内容。
+10. 发送 `status=running`、`step=installed` 结构化状态消息。
+11. 用 OpenClaw 正规配置方式落地本地变更：优先执行 `scripts/grix_agent_bind.py configure-local-openclaw --apply`。该脚本会在写入前临时把 `gateway.reload.mode` 切到 `hot`，避免当前安装对话被自动重启打断；不要手工改完 `openclaw.json` 后再重启 gateway。
+12. 校验目标 agent 仍然可用。
+    - 如果绑定脚本结果里 `runtime_reload.restart_hint_detected=true`，说明当前 OpenClaw 版本仍要求后续重启才能真正启用新配置。此时不要自动重启；如实告诉用户“配置已写入，等待空闲时手动重启生效”，并发 `status=failed`、`error_code=manual_restart_required` 的结构化状态消息后结束。
+    - 其他校验失败 → 尝试回滚（含步骤4新建的远端 agent），无法回滚则如实告知残留状态 → 发 `failed` 结构化状态消息后结束。
+13. 发送 `status=success` 结构化状态消息（带 `target_agent_id`）。
+14. 单独发送目标 agent 的结构化资料卡消息。
+15. 再发一条普通文字，告诉用户可以点开资料卡查看 agent 资料，并从资料页继续与它对话。
+
+### `claude_existing`
+
+1. 确认上下文 route 为 `claude_existing`，且指定的 Claude 目标 agent 存在；**不存在则发 `failed/target_not_found` 结构化状态消息后结束**。
+2. 直接使用 `install.target_agent_id` 指定的 Claude 目标 agent 继续安装，不要重复确认目标；只有目标信息缺失、冲突或执行被阻塞时，才向用户确认。**用户主动取消时发 `failed/user_cancelled` 结构化状态消息后结束**。
 3. 下载 skill 包，并校验 hash / manifest（如果上下文提供）。
-4. 发送 `status=running`、`step=downloaded` 状态指令。
+4. 发送 `status=running`、`step=downloaded` 结构化状态消息。
 5. 用 Claude 正规步骤安装 skill 包。
-6. 发送 `status=running`、`step=installed` 状态指令。
-7. 按需刷新配置或重载运行时。
+6. 发送 `status=running`、`step=installed` 结构化状态消息。
+7. 如需写 OpenClaw 配置，只能走“先切 `gateway.reload.mode=hot` 再写入”的路径；不要在安装对话中执行 `openclaw gateway restart`。
 8. 校验目标 agent 仍然可用。
-    - 校验失败 → 如实告知用户 → 发 `failed` 指令后结束。
-9. 发送 `status=success` 状态指令（带 `target_agent_id`），再向用户汇报完成。
+    - 如果绑定脚本结果里 `runtime_reload.restart_hint_detected=true`，说明当前版本仍需要后续手动重启才能生效。不要自动重启；明确告诉用户配置已写入但待空闲时生效，并发 `failed/manual_restart_required` 结构化状态消息后结束。
+    - 其他校验失败 → 如实告知用户 → 发 `failed` 结构化状态消息后结束。
+9. 发送 `status=success` 结构化状态消息（带 `target_agent_id`）。
+10. 单独发送目标 agent 的结构化资料卡消息。
+11. 再发一条普通文字，告诉用户可以点开资料卡查看 agent 资料，并从资料页继续与它对话。
 
 ## 每次安装至少校验这些点
 
@@ -119,43 +162,56 @@ server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败
 - hash / manifest 校验通过（如果提供）
 - 安装内容已经落到目标位置
 - 目标 agent 安装后仍然可用
+- 实际安装路线没有偏离 `install.route`
 
-## 指令示例
+## 消息示例
+
+进行中（远端 agent 创建完成）：
+
+```json
+{"text":"已创建远端 Agent","channelData":{"grix":{"eggInstall":{"install_id":"eggins_20370001","status":"running","step":"agent_created","summary":"已创建远端 Agent"}}}}
+```
 
 进行中（下载完成）：
 
-```text
-[[egg-install-status|install_id=eggins_20370001|status=running|step=downloaded|summary=%E5%B7%B2%E4%B8%8B%E8%BD%BD%E5%B9%B6%E9%AA%8C%E8%AF%81%E5%AE%89%E8%A3%85%E5%8C%85]]
+```json
+{"text":"已下载并验证安装包","channelData":{"grix":{"eggInstall":{"install_id":"eggins_20370001","status":"running","step":"downloaded","summary":"已下载并验证安装包"}}}}
 ```
 
 进行中（安装落位完成）：
 
-```text
-[[egg-install-status|install_id=eggins_20370001|status=running|step=installed|summary=%E5%AE%89%E8%A3%85%E5%86%85%E5%AE%B9%E5%B7%B2%E8%90%BD%E4%BD%8D%EF%BC%8C%E6%A0%A1%E9%AA%8C%E4%B8%AD]]
+```json
+{"text":"安装内容已落位，校验中","channelData":{"grix":{"eggInstall":{"install_id":"eggins_20370001","status":"running","step":"installed","summary":"安装内容已落位，校验中"}}}}
 ```
 
 成功：
 
-```text
-[[egg-install-status|install_id=eggins_20370001|status=success|step=completed|target_agent_id=2035123456789012345|summary=%E5%B7%B2%E5%AE%8C%E6%88%90%E5%AE%89%E8%A3%85]]
+```json
+{"text":"已完成安装","channelData":{"grix":{"eggInstall":{"install_id":"eggins_20370001","status":"success","step":"completed","target_agent_id":"2035123456789012345","summary":"已完成安装"}}}}
+```
+
+成功后的资料卡：
+
+```json
+{"text":"查看 Agent 资料","channelData":{"grix":{"userProfile":{"user_id":"2035123456789012345","peer_type":2,"nickname":"writer-openclaw"}}}}
 ```
 
 失败（用户取消）：
 
-```text
-[[egg-install-status|install_id=eggins_20370001|status=failed|step=user_cancelled|error_code=user_cancelled|summary=%E7%94%A8%E6%88%B7%E5%8F%96%E6%B6%88%E5%AE%89%E8%A3%85]]
+```json
+{"text":"用户取消安装","channelData":{"grix":{"eggInstall":{"install_id":"eggins_20370001","status":"failed","step":"user_cancelled","error_code":"user_cancelled","summary":"用户取消安装"}}}}
 ```
 
 失败（目标不存在）：
 
-```text
-[[egg-install-status|install_id=eggins_20370001|status=failed|step=target_not_found|error_code=target_not_found|error_msg=%E6%8C%87%E5%AE%9A%E7%9A%84%20Claude%20agent%20%E4%B8%8D%E5%AD%98%E5%9C%A8|summary=%E5%AE%89%E8%A3%85%E5%A4%B1%E8%B4%A5]]
+```json
+{"text":"安装失败","channelData":{"grix":{"eggInstall":{"install_id":"eggins_20370001","status":"failed","step":"target_not_found","error_code":"target_not_found","error_msg":"指定的 Claude agent 不存在","summary":"安装失败"}}}}
 ```
 
 失败（下载失败）：
 
-```text
-[[egg-install-status|install_id=eggins_20370001|status=failed|step=download_failed|error_code=download_failed|error_msg=%E4%B8%8B%E8%BD%BD%E5%AE%89%E8%A3%85%E5%8C%85%E5%A4%B1%E8%B4%A5|summary=%E5%AE%89%E8%A3%85%E5%A4%B1%E8%B4%A5]]
+```json
+{"text":"安装失败","channelData":{"grix":{"eggInstall":{"install_id":"eggins_20370001","status":"failed","step":"download_failed","error_code":"download_failed","error_msg":"下载安装包失败","summary":"安装失败"}}}}
 ```
 
 ## 回复风格

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

@@ -2,14 +2,14 @@
 
 ## Purpose
 
-Unify remote API communication in `egg-install` with the same typed tool pathway used by other grix-admin skills.
+Unify remote API communication in `grix-egg` with the same typed tool pathway used by other grix-admin skills.
 
 ## Base Rules
 
 1. Base path is `/v1/agent-api`.
 2. Auth is `Authorization: Bearer <agent_api_key>`.
 3. Caller must be `provider_type=3` and `status=active`.
-4. `egg-install` must not send direct HTTP requests to Grix by itself.
+4. `grix-egg` must not send direct HTTP requests to Grix by itself.
 
 ## Unified Tool Path
 
@@ -24,6 +24,8 @@ Use only these entry points for remote communication:
 Local binding remains a local operation via bundled script:
 
 - `scripts/grix_agent_bind.py configure-local-openclaw ... --apply`
+- 该脚本会先临时切换 `gateway.reload.mode=hot`，再通过 `openclaw config set` 落配置，避免安装私聊被自动重启打断
+- 如果脚本结果里 `runtime_reload.restart_hint_detected=true`，说明当前版本仍要求后续手动重启才能真正生效；安装私聊里不要执行 `openclaw gateway restart`
 
 ## Prohibited Paths
 
@@ -35,4 +37,5 @@ Local binding remains a local operation via bundled script:
 
 1. Scope/auth/parameter errors: no automatic retry.
 2. Transient network failure: at most one retry, and only after explicit confirmation.
-3. Installation status directives (`egg-install-status`) must still be emitted on terminal success/failure.
+3. Installation status payloads (`channelData.grix.eggInstall`) must still be emitted on terminal success/failure.
+4. On terminal success, emit one additional agent profile payload (`channelData.grix.userProfile`) for the final target agent before sending the plain-language next-step guidance.

package/skills/grix-register/SKILL.md

@@ -14,7 +14,7 @@ description: 仅用于初次安装阶段，完成 Grix 环境的账号注册/登
 
 1. 本技能**只能**做账号与云端 Agent 参数准备。
 2. 本技能**不能**执行 `openclaw` 命令，也不能修改本地 `openclaw.json`。
-3. 涉及本地配置、插件安装、工具权限、重启网关，一律交给 `grix-admin`。
+3. 涉及本地配置、插件安装、工具权限、热加载校验，一律交给 `grix-admin`。
 
 ### 1. 询问邮箱并发送验证码
 

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

@@ -21,4 +21,4 @@
 1. `mode` 固定为 `bind-local`。
 2. `agent_name`、`agent_id`、`api_endpoint`、`api_key` 必填。
 3. `grix-register` 只负责生成以上参数，不执行本地配置命令。
-4. 本地写入、插件处理、工具权限、gateway 重启都由 `grix-admin` 负责。
+4. 本地写入、插件处理、工具权限、热加载校验都由 `grix-admin` 负责。

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

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