---
name: grix-egg
description: "Grix egg market for OpenClaw — the FIRST entry when the user wants a new agent or assistant for some purpose: search published eggs (skill and persona packages) with `grix_egg_search` / `grix_egg_get`, present matches, and hatch the chosen one yourself from the package URLs `grix_egg_get` returns (via the `grix_egg` tool); only when nothing fits fall back to grix-admin. Hatching itself is program-driven: AI organizes parameters and calls `grix_egg`; the program handles creation, installation, binding, acceptance, and status reporting."
---

# Grix Egg

## 0. Discovery first — find an egg before creating an agent

When the user describes an agent they want ("帮我建一个跟进外贸询盘的助手",
"I need a bot that reviews PRs") and there is no install card yet, search the
egg market before anything else; do **not** go to `grix-admin`.

1. Distill the description into **2–4 short keywords** (role noun, domain,
   core action). The backend ANDs terms against name + description +
   category, so a whole sentence returns nothing.
2. Call `grix_egg_search` **once per keyword** (`pageSize` 10) in the user's
   language / `locale`; merge, rank by keyword hits then `install_count`. If
   nothing matches, browse by `categoryId` with no keyword.
3. Show at most 3–5 candidates: name (+ emoji), one-line description,
   category, `install_count`, and whether it hatches a **new agent**
   (`can_create_agent`) or installs as a **skill into an existing agent**
   (`existing_agent_client_types`). `grix_egg_get` gives the full text.
4. The user picks one → `grix_egg_get` returns the package URLs
   (`persona_zip_url` / `skill_zip_url`, each with a `*_sha256`). Call
   `grix_egg` with structured parameters (section 3, no install card):
   `route: create_new` + `agentName` + `introduction` + `downloadUrl` =
   `persona_zip_url` for a new agent, or `route: existing` + `downloadUrl`
   for an existing one; pass the sha256 as `packageHash`. No `installId`
   exists in this path, so no status card is sent.
5. No egg fits, or the user explicitly wants a blank agent → hand over to
   `grix-admin` and say clearly that no ready-made egg matched.

`grix-egg` follows a "program-first, AI-assists" approach.
AI no longer manually relays create/bind/accept.

## 1. AI Role Boundary

You only do three things:

1. Organize user input into standard parameters
2. Call `grix_egg`
3. Report results / request supplementary parameters based on the returned JSON

Do not manually execute these actions:

1. Remote agent creation
2. Local bind
3. Gateway operations
4. Test group acceptance

## 2. Agent Profile Intake

Before calling `grix_egg` with `route=create_new`:

1. Ensure the request has both a concrete Agent name and a usable introduction.
2. If either one is missing or too vague, pause and ask one concise question: “这个 Agent 主要做什么？核心职责、服务对象和工作边界是什么？” Do not start hatching yet.
3. Turn the user's answer into a concise professional `agentName` and a professional `introduction`. The introduction must describe purpose, core responsibilities, intended users or scenarios, operating expectations, and important boundaries.
4. Preserve the user's facts and intent; do not invent permissions, authority, expertise, or responsibilities.
5. Treat the introduction as the Agent's behavioral specification. Pass it through the actual `introduction` parameter so the program sends it in `grix_admin action=create_agent`; do not leave it only in chat, `soulContent`, or persona files.
6. When using a raw `installContext` that lacks the finalized profile, pass `agentName` and `introduction` alongside it as explicit overrides.

## 3. Standard Call Entry

Prefer passing the raw install card:

```json
{ "installContext": "<raw json>" }
```

If there is no install card, pass structured parameters:

1. `route`: `create_new` | `existing` | `existing_claude`
2. `agentName` (required for `create_new`)
3. `introduction` (required for `create_new`; professionally organized according to **Agent Profile Intake**)
4. `agentIdSlug` or `localAgentName`
5. `downloadUrl`
6. `existingCredentials` (required for `existing`)
7. Optional: `packageHash`, `soulContent`, `soulFile`, `categoryId`, `categoryName`, `isMain`, `expectedSubstring`, `statusTarget`, `resume`, `installId`

## 4. Route Behavior

1. `create_new`: program automatically completes creation, installation, binding, acceptance, and status reporting
2. `existing`: program automatically completes existing credential installation and acceptance
3. `existing_claude`: program returns `unsupported_route`, handled by a standalone Claude installer

## 5. Acceptance Rules

Program has fixed acceptance logic:

1. Test group members must include: main agent, trigger user, target agent
2. Probe uses `@<target_agent_id>` mention
3. Only the first non-empty reply after the probe from the target agent is accepted
4. `expectedSubstring` is only an optional enhancement condition

## 6. Result Reporting

When `ok=true`:

1. Report `install_id`, `route`, target agent, acceptance result
2. If `acceptance.reply_content` and `testGroup` are present, include them for the user
3. If `interaction_status=degraded`, explain that the main flow succeeded but status reporting partially failed

When `ok=false`:

1. Use `reason` and `suggestion` directly to explain the failure
2. Only supplement external inputs that the program explicitly identifies as missing
3. Use `resume=true` + `installId` when continuation is needed

## 7. Prohibited Actions

1. Do not use `curl`/`fetch`/`axios` to directly connect to `/v1/agent-api`
2. Do not manually modify `openclaw.json`
3. Remote actions must only go through typed tools: `grix_admin`, `grix_group`, `grix_query`
4. Do not claim installation success before acceptance is complete

## References

1. [references/api-contract.md](references/api-contract.md)