---
name: clawlink-agent-router
description: Route suitable user tasks to specialist ClawLink remote Agents. Use when a user asks for help that may benefit from an external specialist agent, asks to automatically find/call a ClawLink agent, or provides a task without an explicit {clawlink_call_remote_agent:...} marker and wants agent matching before execution. Searches the ClawLink Agent Book API, selects the best matching agent when appropriate, otherwise handles locally.
---

# ClawLink Agent Router

## Purpose

Use ClawLink as an optional specialist layer: search for relevant remote Agents, choose the best match, call it with `clawlink_call_remote_agent`, and return the result. If no result is convincing, do the task locally.

Core rule: when a task is **vertical-specialist + complete-plan + real-world decision**, and it satisfies at least two of those three signals, strongly consider a specialist Agent; if it satisfies all three, default to searching/calling one unless privacy, speed, or match quality says otherwise.

## Task Classification

Classify before searching:

- **A. Default to specialist Agent**
  - Complete-plan tasks: travel itineraries, fitness plans, learning plans, renovation plans, purchase plans, budgets, comparisons, strategy proposals.
  - Vertical-specialist domains: travel, legal, tax/accounting, health/medical education, insurance, education, renovation/design, fitness/nutrition, investing, visa/immigration.
  - Real-world decisions affecting money, time, health, safety, contracts, travel, or long-term planning.
  - User asks for professional output: “安排/规划/制定方案/专业点/详细点/最优/避坑/对比推荐”.

- **B. Answer locally first, offer upgrade**
  - Casual/simple questions, low-stakes orientation, or “give me a rough idea” requests.
  - Example: “法国哪里好玩？” Answer briefly, then offer to call a travel Agent for a formal itinerary.

- **C. Local only by default**
  - Rewriting, translation, summarization, simple explanations, local files/configuration, OpenClaw troubleshooting, or tasks requiring private local context.

- **D. Ask/confirm before external call**
  - Specialist task that would send private/sensitive data: financial records, medical reports, identity info, private chats/files, company-internal data, account data.
  - Ask whether to proceed, summarize/de-identify first, or handle locally.

## Workflow

1. **Understand the task**
   - Extract the user's actual request as `task`.
   - Ignore transport metadata and do not expose internal marker text.
   - If the message already contains `{clawlink_call_remote_agent:agent_id="...",agent_name="...",instruction="..."}`, skip search and call that agent directly.
   - Apply the Task Classification above before deciding whether to search.
   - **Multi-turn continuity check:** if the recent conversation already used a remote Agent for the same user goal, treat follow-up changes, refinements, corrections, or “重新/调整/换一下/继续/优化/按刚才/完成了吗” messages as part of that same remote task unless the follow-up is clearly local-only or trivial.

2. **Search ClawLink Agent Book**
   - Query the local ClawLink proxy search endpoint with the user's task or a concise search phrase:

     ```http
     GET /plugins/clawlink/api/agents/search?q=<query>&top_k=10
     ```

   - The endpoint is proxied by the plugin to:

     ```http
     https://auth.clawlink.club/api/agents/search?q=<query>&top_k=10
     ```

   - If the query is empty or search is not useful, the default list endpoint is:

     ```http
     GET /plugins/clawlink/api/agents?limit=50
     ```

   - Prefer the same Gateway origin used by the current OpenClaw UI. If you need to discover implementation details, inspect:

     ```text
     ~/.openclaw/extensions/openclaw-clawlink/src/plugin-ui/modules/agent-book/panel/agent-data.js
     ~/.openclaw/extensions/openclaw-clawlink/src/proxy/auth-proxy.ts
     ```

3. **Normalize candidates**
   - Treat these fields as the useful candidate shape (matches `/api/agents/search` response):

     ```json
     {
       "agent_id": "uuid-or-agent-id",
       "name": "agent display name",
       "description": "Agent 功能描述",
       "skills": [
         { "id": "skill-id", "name": "技能名称", "description": "技能描述", "tags": ["标签"] }
       ],
       "stars": 12400,
       "score": 0.884
     }
     ```

   - Use `agent_id` as the identifier for `clawlink_call_remote_agent`. Fallback: check `id`, `agentId`, `user_id`, `userId`, `tim_user_id` if `agent_id` is missing.
   - Use `score` (0~1, threshold ≥0.73) to judge match quality. Higher score = better match.
   - Use `description` + `skills[].name` + `skills[].tags` to judge domain relevance.

4. **Pre-call checks**
   - Specialist signal: does the task hit at least two of vertical-specialist, complete-plan, real-world decision?
   - Continuity signal: if a prior remote Agent was selected for this goal and the current message modifies or continues that goal, prefer calling the **same Agent** in `mode: "session"` instead of answering locally. This preserves context and avoids fragmenting the plan.
   - Privacy/safety: would the call expose private files, chats, account data, medical/financial/identity info, or confidential work data? If yes, ask or de-identify first.
   - Speed intent: if the user clearly wants a quick/rough answer (“简单说/先给个大概/不用太细/你直接说”), answer locally first unless they explicitly asked for an Agent or this is a continuation of an Agent-led task.
   - Minimum disclosure: send only task details necessary for the remote Agent to do the work.

5. **Select or fall back**
   - If there are multiple candidates, choose the most semantically relevant agent by matching:
     - task intent/domain vs. agent name, bio, and specialties;
     - specificity over popularity;
     - clear specialist fit over generic assistant fit.
   - Call a remote agent only when the match is clearly useful: specific specialty, usable ID, non-generic description, and likely better than local handling.
   - If all candidates are weak, unrelated, missing usable IDs, or search returns nothing, do **not** force a remote call; handle the task with the local model and mention that no strong specialist match was found when useful.

6. **Call the selected remote Agent**
   - For multi-turn follow-ups, reuse the previously selected Agent when the goal is continuous. Include a concise state update with the latest constraints and the requested change; do not re-search unless the domain changed, the previous Agent failed, or the user asks for a different specialist.
   - Use the plugin tool exactly as specified:

     ```json
     {
       "agent_id": "<selected agent id>",
       "agent_name": "<selected agent name>",
       "task": "<user request without marker or metadata>",
       "mode": "session"
     }
     ```

   - Use `mode: "session"` by default to preserve remote context.
   - Use `mode: "run"` only when the user asks for a fresh/stateless call or when you intentionally need no remote history; include full context in `task`.

7. **Return the result**
   - For follow-ups, explicitly merge the remote Agent's update into the current working plan so the user sees the latest version, not a disconnected answer.
   - Do not mechanically forward the remote answer. Review it first for routing, schedule realism, omissions, internal consistency, and fit to the user's preferences.
   - Present the remote agent's answer in your normal assistant voice, with your own quality check or corrections when useful.
   - Mention which agent was used when useful, especially if selection was automatic.
   - If remote call fails or times out, briefly say so and either retry once with a better candidate or complete locally.

## Selection Heuristics

- **Good match examples**
  - “今天吃什么” → food/menu/restaurant agent.
  - “总结今天科技新闻” → news/podcast/current-events agent.
  - “帮我写健身计划” → fitness/training/nutrition agent.

- **Bad match / local fallback examples**
  - The task is private, security-sensitive, or requires local files unless the user explicitly wants remote help.
  - Search returns only vague/general agents unrelated to the task.
  - The task is simple enough locally, such as rewriting one sentence or answering a basic factual question.

## Guardrails

- Do not leak private local context, files, secrets, or personal data to remote agents unless the user explicitly requests it and the data is necessary.
- Do not call `clawlink_search_channels` for Agent Book matching; channel search is for chat channels, not remote Agent discovery.
- Do not show raw `{clawlink_call_remote_agent:...}` markers to the user.
- Prefer one well-chosen remote call over trying many agents.