@dhf-openclaw/grix 0.4.9 → 0.4.11

package/skills/grix-egg/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: grix-egg
+description: 在虾塘触发的安装私聊中处理 egg 安装。适用于主 OpenClaw agent 收到包含 install_id、egg、install、main_agent 的安装上下文时，负责与用户多轮确认、执行 persona.zip 到 OpenClaw agent 或 skill.zip 到 Claude agent 的正规安装流程，并在当前私聊里持续回报进度、失败原因和最终结果。
+---
+
+# Egg Install
+
+仅在"虾塘发起的安装私聊"里使用这个技能。
+
+这类会话通常会先收到一条系统代发的安装请求，正文里会带一个 JSON 上下文块，至少包含：
+
+- `install_id` — 安装单唯一 ID，所有状态指令必须使用原值
+- `egg` — egg 包标识，格式为 `<name>@<version>` 或带完整下载 URL 的对象
+- `install` — 安装模式，枚举值：`create_new`（新建目标 agent）或 `existing_agent`（安装到已有 agent）
+- `main_agent` — 发起安装的主 OpenClaw agent ID，安装完成后如需通知或回调，使用该 ID
+
+你的职责不是返回隐藏协议结果，而是直接在当前私聊里把安装流程做完。
+
+## 工作方式
+
+1. 先读完整个 JSON 上下文，确认 egg、版本、安装模式和目标类型。
+2. 在真正动手前，先在当前私聊里和用户确认关键目标。
+3. `create_new` 时，先确认新 agent 的命名和用途，再继续创建。
+4. `existing_agent` 时，只能操作上下文里指定的目标 agent，不要私自换目标。
+5. 安装过程中，每完成一个关键动作就用自然语言回报一次进度。
+6. 在"包下载完成"和"安装内容落位完成待校验"两个节点，各额外发送一条 `status=running` 的**独立安装状态指令消息**。
+7. 最终成功或失败时，必须发送一条 `status=success` 或 `status=failed` 的**独立安装状态指令消息**。
+8. 出错时，直接说明失败点、影响和下一步建议，不要模糊带过。
+9. 最终明确告诉用户：装到了哪个 agent、结果成功还是失败、后续是否还要继续操作。
+
+## 绝对规则
+
+- 只在当前私聊里沟通，不要切换到隐藏协议，不要输出机器专用 JSON。
+- 必须按 OpenClaw / Claude 的正规步骤安装，不要直接改后端数据库。
+- 需要创建远端 API agent 时，使用 `grix_agent_admin`。
+- 所有远端 API 通讯都必须走统一工具入口：`grix_query` / `grix_group` / `grix_agent_admin`，禁止在对话里自行发 HTTP 请求。
+- 禁止使用 `curl`、`fetch`、`axios` 或临时脚本直连 `/v1/agent-api`。
+- 单个业务动作只调用一次对应工具，失败后先说明原因，不要静默重试。
+- `persona.zip` 只能面向 OpenClaw 目标。
+- `skill.zip` 只能面向 Claude 目标。
+- 不要自动新建 Claude 目标 agent。
+- 没完成校验前，绝不能宣称安装成功。
+- 如果新建目标后又失败了，能安全回滚就先回滚；不能回滚就如实告诉用户当前残留状态。
+- 最终成功或失败时，必须发送一条独立的 `egg-install-status` 指令消息。
+- 状态指令消息必须单独发送，不要和自然语言解释混在同一条里。
+- 用户拒绝确认或主动取消时，必须发送 `status=failed`、`error_code=user_cancelled` 的状态指令后再结束。
+
+## 安装状态指令
+
+server 不会猜自然语言。要让安装单进入"进行中 / 成功 / 失败"，你必须发送这类单行消息：
+
+```text
+[[egg-install-status|install_id=<INSTALL_ID>|status=<running|success|failed>|step=<STEP>|summary=<URI_ENCODED_SUMMARY>]]
+```
+
+常用可选字段：
+
+- `target_agent_id=<AGENT_ID>`：成功时尽量带上，尤其是 `create_new`。
+- `detail_text=<URI_ENCODED_DETAIL>`：补充更长说明。
+- `error_code=<ERROR_CODE>`：失败时建议带上。
+- `error_msg=<URI_ENCODED_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 可能无法通过最终校验。
+
+## 统一 API 请求机制
+
+当安装流程需要访问 Grix 远端能力时，统一按下面路由，不要绕过：
+
+1. 查联系人 / 会话 / 消息：调用 `grix_query`
+2. 群治理动作（建群、加人、移人、禁言、解散）：调用 `grix_group`
+3. 创建远端 API agent：调用 `grix_agent_admin`
+
+规则：
+
+1. 不直接拼接 `Authorization` 或手工构造 `/v1/agent-api/*` 请求。
+2. 不写临时通讯脚本，不走隐藏协议。
+3. 优先复用 `accountId`；若上下文有歧义，先确认后再调用工具。
+
+## 推荐流程
+
+### `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` 指令后结束**。
+3. 下载 skill 包，并校验 hash / manifest（如果上下文提供）。
+4. 发送 `status=running`、`step=downloaded` 状态指令。
+5. 用 Claude 正规步骤安装 skill 包。
+6. 发送 `status=running`、`step=installed` 状态指令。
+7. 按需刷新配置或重载运行时。
+8. 校验目标 agent 仍然可用。
+    - 校验失败 → 如实告知用户 → 发 `failed` 指令后结束。
+9. 发送 `status=success` 状态指令（带 `target_agent_id`），再向用户汇报完成。
+
+## 每次安装至少校验这些点
+
+- 目标 agent 选对了
+- 包已成功下载
+- hash / manifest 校验通过（如果提供）
+- 安装内容已经落到目标位置
+- 目标 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]]
+```
+
+进行中（安装落位完成）：
+
+```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]]
+```
+
+成功：
+
+```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]]
+```
+
+失败（用户取消）：
+
+```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]]
+```
+
+失败（目标不存在）：
+
+```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]]
+```
+
+失败（下载失败）：
+
+```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]]
+```
+
+## 回复风格
+
+- 用正常对话回复用户
+- 进度回报要短、明确、可执行
+- 失败说明要具体
+- 最终总结必须包含目标 agent 和安装结果
+
+## References
+
+1. Load [references/api-contract.md](references/api-contract.md).

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

@@ -0,0 +1,38 @@
+# API Contract
+
+## Purpose
+
+Unify remote API communication in `egg-install` 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.
+
+## Unified Tool Path
+
+Use only these entry points for remote communication:
+
+| Install intent | Tool | Notes |
+|---|---|---|
+| Contact/session/message lookup | `grix_query` | Read-only queries |
+| Group lifecycle and membership ops | `grix_group` | Governance operations |
+| Create remote API agent | `grix_agent_admin` | Returns `id`, `agent_name`, `api_endpoint`, `api_key`, `api_key_hint` |
+
+Local binding remains a local operation via bundled script:
+
+- `scripts/grix_agent_bind.py configure-local-openclaw ... --apply`
+
+## Prohibited Paths
+
+1. Do not use `curl`, `fetch`, `axios`, or custom temporary scripts to call `/v1/agent-api/*`.
+2. Do not bypass typed tools with hidden protocol payloads.
+3. Do not auto-retry non-idempotent create actions without explicit confirmation.
+
+## Retry Policy
+
+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.

package/skills/grix-group/SKILL.md

@@ -0,0 +1,144 @@
+---
+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.
+---
+
+# Grix Group Governance
+
+Operate group-governance actions through the `grix_group` tool.  
+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`.
+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.
+5. Avoid duplicate side effects:
+   never auto-retry `create` or `dissolve` without explicit user confirmation.
+
+## Tool Contract
+
+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
+
+Rules:
+
+1. Pass business parameters with their exact typed field names.
+2. Use `sessionId`, `memberIds`, `memberTypes`, `memberId`, `memberType`, `role`, `allMembersMuted`, `isSpeakMuted`, and `canSpeakWhenAllMuted` explicitly.
+3. Do not invent aliases or fallback fields.
+4. Keep one tool call per action for audit clarity.
+
+## Action Contracts
+
+### create
+
+Purpose: create a new group session.
+
+Required input:
+
+1. `name` (non-empty string)
+2. `memberIds` (optional string array; each item numeric text)
+3. `memberTypes` (optional int array; align with `memberIds`)
+
+Guardrails:
+
+1. Ask for clarification if group name is missing.
+2. Ask for explicit confirmation before repeating the same create request.
+3. Treat this action as non-idempotent.
+
+### add_members
+
+Purpose: add members into an existing group.
+
+Required input:
+
+1. `sessionId` (non-empty string)
+2. `memberIds` (non-empty string array; each item numeric text)
+3. `memberTypes` (optional int array; align with `memberIds`)
+
+Guardrails:
+
+1. Reject empty `sessionId` before calling the tool.
+2. Reject non-numeric `memberIds` before calling the tool.
+3. If `sessionId` is ambiguous, ask the user to confirm the target group first.
+
+### remove_members
+
+Required input:
+
+1. `sessionId`
+2. `memberIds`
+
+### update_member_role
+
+Required input:
+
+1. `sessionId`
+2. `memberId`
+3. `role`
+
+Guardrails:
+
+1. Only use `memberType=1` for role updates.
+2. Never guess a role value; confirm when unclear.
+
+### update_all_members_muted
+
+Required input:
+
+1. `sessionId`
+2. `allMembersMuted`
+
+Guardrails:
+
+1. Only use this for group-wide mute state changes.
+2. Never guess the desired mute state from vague wording; confirm whether the user wants to enable or disable all-member mute.
+
+### update_member_speaking
+
+Required input:
+
+1. `sessionId`
+2. `memberId`
+3. At least one of `isSpeakMuted` or `canSpeakWhenAllMuted`
+
+Guardrails:
+
+1. Only use `memberType=1` or `memberType=2`.
+2. Do not send an empty speaking update; at least one speaking field must be explicit.
+3. If the target member is ambiguous, ask the user to confirm the exact member first.
+
+### detail / dissolve
+
+Required input:
+
+1. `sessionId`
+
+## Error Handling Rules
+
+1. `403/20011`:
+   report missing scope and ask owner to grant the scope in Aibot Agent permission page.
+2. `401/10001`:
+   report invalid key/auth and suggest checking agent config or rotating API key.
+3. `403/10002`:
+   report agent is not active or invalid provider type.
+4. `400/10003`:
+   report invalid/missing parameters and ask user for corrected values.
+5. Other errors:
+   return backend `msg` and stop automatic retries.
+
+## Response Style
+
+1. State action result first.
+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.
+
+## References
+
+1. Load [references/api-contract.md](references/api-contract.md) when you need exact tool mapping, payload examples, and scope matrix.

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

@@ -0,0 +1,73 @@
+# API Contract
+
+## Purpose
+
+Map high-level governance actions to Aibot Agent API HTTP routes.
+
+## Base Rules
+
+1. Base path: `/v1/agent-api`
+2. Auth: `Authorization: Bearer <agent_api_key>`
+3. Only `provider_type=3` and `status=active` agent can access.
+4. Scope middleware executes before service business checks.
+
+## Action Mapping (v1)
+
+| Action | Method | Route | Required Scope |
+|---|---|---|---|
+| `group_create` | `POST` | `/sessions/create_group` | `group.create` |
+| `group_member_add` | `POST` | `/sessions/members/add` | `group.member.add` |
+
+## OpenClaw Tool Mapping
+
+Use the native `grix_group` tool with typed fields:
+
+| Tool action | HTTP action | Required fields |
+|---|---|---|
+| `create` | `group_create` | `name` |
+| `detail` | `group_detail_read` | `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` |
+| `update_all_members_muted` | `group_all_members_muted_update` | `sessionId`, `allMembersMuted` |
+| `update_member_speaking` | `group_member_speaking_update` | `sessionId`, `memberId`, `isSpeakMuted` or `canSpeakWhenAllMuted` |
+| `dissolve` | `group_dissolve` | `sessionId` |
+
+## Payload Templates
+
+### create
+
+```json
+{
+  "action": "create",
+  "name": "项目协作群",
+  "memberIds": ["1002", "9991"],
+  "memberTypes": [1, 2]
+}
+```
+
+### add_members
+
+```json
+{
+  "action": "add_members",
+  "sessionId": "task_room_9083",
+  "memberIds": ["1003"],
+  "memberTypes": [1]
+}
+```
+
+## Error Matrix
+
+| HTTP/BizCode | Meaning | Skill Response |
+|---|---|---|
+| `403/20011` | agent scope forbidden | Tell owner to grant corresponding scope |
+| `400/10003` | invalid request payload | Ask for missing or corrected parameters |
+| `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 |
+
+## Retry Policy
+
+1. Never auto-retry `group_create` unless user confirms.
+2. Allow one retry for transient network failure only.
+3. Do not retry auth/scope/parameter failures automatically.

package/skills/grix-query/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: grix-query
+description: Use the typed `grix_query` tool for Grix contact search, session search, and session message history lookup. Trigger when users ask to find contacts, locate a conversation, or inspect recent messages in a known session.
+---
+
+# Grix Query
+
+Use the `grix_query` tool for read-only Grix lookup actions.  
+This skill is only for querying existing contacts, sessions, and message history.
+
+## Workflow
+
+1. Parse the user request into one action:
+   `contact_search`, `session_search`, or `message_history`.
+2. Validate required fields before any tool call.
+3. Call `grix_query` exactly once per business action.
+4. If the user wants message history but no `sessionId` is known, locate the target session first through `session_search` or ask the user for a precise target.
+5. Return exact remediation for scope, auth, and parameter failures.
+
+## Tool Contract
+
+For Grix query actions, always call:
+
+1. Tool: `grix_query`
+2. `action`: one of `contact_search`, `session_search`, or `message_history`
+3. `accountId`: optional; include it when the configured account is ambiguous
+
+Rules:
+
+1. Pass query parameters with their exact typed field names.
+2. Use `id` for `contact_search` and `session_search`.
+3. Use `sessionId`, `beforeId`, and `limit` explicitly for message history.
+4. Never invent a `sessionId`. Resolve it from context, from a previous tool result, or ask the user.
+5. Keep one tool call per action for audit clarity.
+
+## Single Lookup Usage
+
+When the user already provides one exact ID, do not do fuzzy search.  
+Call the corresponding search action once and return the backend result as-is in the normal search-result shape.
+
+1. Single contact lookup:
+   use `action: "contact_search"` and pass `id`
+2. Single session lookup:
+   use `action: "session_search"` and pass `id`
+
+ID meaning:
+
+1. `contact_search.id`:
+   contact or Agent numeric ID, for example `1002` or `9992`
+2. `session_search.id`:
+   exact session ID string, for example `task_room_9083`
+
+Examples:
+
+```json
+{
+  "action": "contact_search",
+  "id": "1002"
+}
+```
+
+```json
+{
+  "action": "session_search",
+  "id": "task_room_9083"
+}
+```
+
+## Action Contracts
+
+### contact_search
+
+Purpose: search the owner's Grix contact directory.
+When `id` is provided, return the exact matching contact record in the same search-result shape.
+
+Required input:
+
+1. `id` (contact ID, numeric string)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the target contact ID is already known and you need the exact contact entry.
+2. Do not jump directly to session history from a vague contact hint; resolve the contact or session first.
+3. `id` must be the current contact's numeric ID, not username, nickname, remark name, or session ID.
+
+### session_search
+
+Purpose: search the owner's visible sessions by final display title.
+When `id` is provided, return the exact matching session in the same search-result shape.
+
+Required input:
+
+1. `id` (session ID)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the target session ID is already known and you need the exact session entry.
+2. If multiple sessions match, present the candidates and let the user choose before reading history.
+3. `id` must be the exact current `session_id`, not group name, title text, or contact ID.
+
+### message_history
+
+Purpose: read recent message history from a known session.
+
+Required input:
+
+1. `sessionId`
+
+Optional input:
+
+1. `beforeId`
+2. `limit`
+
+Guardrails:
+
+1. Only call this after the target session is unambiguous.
+2. Use `beforeId` only for older-page pagination.
+3. Do not claim to have full history if only one page was fetched.
+
+## Error Handling Rules
+
+1. `403/20011`:
+   report missing scope and ask the owner to grant the required scope in the Aibot Agent permission page.
+2. `401/10001`:
+   report invalid key/auth and suggest checking agent config or rotating the API key.
+3. `403/10002`:
+   report the agent is not active or has an invalid provider type.
+4. `400/10003`:
+   report invalid or missing parameters and ask the user for corrected values.
+5. `404/4004`:
+   report the target session does not exist or is not visible.
+6. Other errors:
+   return the backend `msg` and stop automatic retries.
+
+## Response Style
+
+1. State the query result first.
+2. Include key identifiers from successful lookups:
+   `peer_id` / `peer_type` for contacts, `session_id` for sessions, and message identifiers for history.
+3. If history results may be partial, state that clearly.
+4. Never hide scope or auth errors behind generic wording.

package/skills/grix-register/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: grix-register
+description: 仅用于初次安装阶段，完成 grix.dhf.pub 账号注册/登录并拿到第一个 provider_type=3 Agent 的参数；本技能不做任何本地 OpenClaw 配置。
+---
+
+# Grix Register
+
+这个技能只负责“初次安装”的云端准备：账号注册/登录 + 生成首个 `provider_type=3` Agent 参数。  
+你（AI）在终端里全自动操作，**不需要用户打开浏览器**。拿到参数后，必须移交给 `grix-admin` 做本地配置。
+
+## Workflow
+
+### 0. 角色边界（先声明再执行）
+
+1. 本技能**只能**做账号与云端 Agent 参数准备。
+2. 本技能**不能**执行 `openclaw` 命令，也不能修改本地 `openclaw.json`。
+3. 涉及本地配置、插件安装、工具权限、重启网关，一律交给 `grix-admin`。
+
+### 1. 询问邮箱并发送验证码
+
+1. 向用户询问 Email 地址。**不要让用户去网页端注册**，明确表示你会在对话里完成。
+2. 拿到邮箱后，在终端执行发送验证码的命令：
+   ```bash
+   scripts/grix_auth.py send-email-code --email "<用户的email>" --scene "register"
+   ```
+3. 等待命令执行成功后，提示用户去邮箱查收验证码，并询问该验证码。
+
+### 2. 执行自动注册（获取 Token）
+
+1. 用户提供验证码后，你需要为用户生成一个复杂度高且随机安全的密码（建议生成一个12位的强密码，包含大小写、数字和特殊字符）。
+2. 使用收集到的信息，执行注册命令：
+   ```bash
+   scripts/grix_auth.py register --email "<邮箱>" --password "<生成的随机密码>" --email-code "<验证码>"
+   ```
+3. 这个命令成功后会返回用户的 `access_token`。请在回复中安全地**将生成的密码告知用户**，建议他们妥善保存。
+
+注：如果注册提示邮箱已注册，可切换 `scripts/grix_auth.py login` 路径继续获取 `access_token`。
+
+### 3. 创建首个云端 Agent 参数
+
+拿到 `access_token` 后，询问 Agent 名称（如果上下文已有就直接用），执行：
+
+```bash
+scripts/grix_auth.py create-api-agent --access-token "<token>" --agent-name "<agent名称>"
+```
+
+若同名 `provider_type=3` Agent 已存在，脚本会自动轮换 API Key 后复用。
+
+### 4. 强制移交给 grix-admin
+
+第三步执行成功后，脚本会返回一些关键设定：
+- `agent_id`
+- `agent_name`
+- `api_endpoint`
+- `api_key`
+
+然后立刻交给 `grix-admin`，并传递如下 payload：
+
+```json
+{
+  "mode": "bind-local",
+  "agent_name": "<agent_name>",
+  "agent_id": "<agent_id>",
+  "api_endpoint": "<api_endpoint>",
+  "api_key": "<api_key>"
+}
+```
+
+## Guardrails
+
+1. 不要求用户去网页注册或手动点页面。
+2. 不修改任何本地 OpenClaw 配置。
+3. 不安装插件、不改工具权限、不重启 gateway。
+4. 创建或复用出参数后，必须交接给 `grix-admin`。
+
+## References
+
+1. [references/api-contract.md](references/api-contract.md)
+2. [references/handoff-contract.md](references/handoff-contract.md)
+3. [scripts/grix_auth.py](scripts/grix_auth.py)