openclaw-agent-feishu-onboarding

# OpenClaw Agent Feishu Onboarding Standardize creation of new OpenClaw agents and Feishu route binding. Use this skill for operational execution with strict confirmations. ## Runtime Prerequisites - Required binaries: - `openclaw` (CLI available in PATH) - `python` (3.x, used by `scripts/validate_feishu_bindings.py`) - Preflight checks: - `openclaw --version` - `python --version` - Data access behavior: - Reads local OpenClaw config (`openclaw.json` / `OPENCLAW_CONFIG_PATH`) - May write local agent and routing state (`agents.list[]`, `bindings[]`) - Do not run on machines where local config access is not permitted ## Core Scope - Create a new agent (`agents.list` + workspace + identity). - Confirm Feishu route target fields before any write. - Bind routing using `bindings.match` with `channel/accountId/peer`. - Verify final route and provide rollback steps. ## Required Inputs - Agent intent: - Agent purpose and responsibility boundary. - Explicit out-of-scope items. - Agent spec: - `agentId` (lowercase, digits, hyphen). - `workspace` path. - `model` id. - Identity object in `agents.list[]`: - use `identity` object (for example `identity.name`, `identity.emoji`, `identity.theme`) - do not rely on top-level `name` only - Feishu route spec: - `match.channel`: `feishu` - `match.accountId`: for example `main` - `match.peer.kind`: `group` (or `dm` when needed) - `match.peer.id`: Feishu session id (group id like `oc_xxx` or dm id) ## Hard Validation Gates (Must Pass) - `agents.list[]` entry for new agent must include `identity` object. - `identity.name` must be set for human-readable routing/debug checks. - `match.accountId` must be one of `channels.feishu.accounts` keys (for example `main`). - Never put Feishu group/session id (`oc_xxx`) into `match.accountId`. - Group routing must include `match.peer = { kind: "group", id: "oc_xxx" }`. - If routing is for a specific group but `match.peer` is missing, abort and correct config before continuing. - Before write, print the final binding object and require explicit confirmation. ## Multi-Step Confirmation Protocol Do not skip confirmations. Ask and confirm in this exact order. 1. Confirmation A: Agent Goal - Confirm what this agent should do. - Confirm what this agent must not do. 2. Confirmation B: Agent Configuration - Confirm `agentId`, `workspace`, model, identity fields. - Confirm naming conventions and collision check (`agentId` uniqueness). 3. Confirmation C: Feishu Routing Target - Confirm `accountId`. - Confirm `peer.kind`. - Confirm `peer.id` (explicitly state this is the Feishu session id). - Confirm whether this is a precise peer binding or account-level fallback. 4. Confirmation D: Execution Approval - Summarize all fields in one compact block. - Ask for final go/no-go before writing config. ## Execution Workflow 1. Discover current state: - `openclaw agents list` - `openclaw config get agents.list --json` - `openclaw config get channels.feishu.accounts --json` - `openclaw directory groups list --channel feishu --account <account-id> --query "<keyword>" --json` - `openclaw config get bindings --json` 2. Create agent: - `openclaw agents add ...` - Optional: `openclaw agents set-identity ...` 3. Apply routing: - Use `openclaw agents bind` for account-scoped binding when needed. - Ensure peer-precise rule exists in top-level `bindings[]` with `match.peer`. 4. Validate: - `python -X utf8 ./scripts/validate_feishu_bindings.py --config <openclaw.json-path>` - `openclaw config validate --json` - ensure target `agents.list[]` entry has `identity.name` - Check `bindings[]` entry content and ordering. - Ensure every group-targeted rule has `match.peer.kind = "group"` and `match.peer.id = "oc_xxx"`. 5. Reload/restart gateway if required by deployment policy. ## Routing Rules - `peer` rule is the precise route key for a specific Feishu conversation. - Use `match.peer.id` to bind a specific session (group `oc_xxx`). - If both peer-level and account-level bindings exist, keep peer rule first. - Avoid broad fallback rules until peer-specific routes are confirmed. - Wrong example (forbidden): `match.accountId: "oc_xxx"` without `match.peer`. Agent list entry should follow this shape: ```json { "id": "data-analyst", "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace-dataAnalysis", "agentDir": "C:\\Users\\Administrator\\.openclaw\\agents\\data-analyst\\agent", "identity": { "name": "data-analyst" } } ``` Canonical peer binding object: ```json { "agentId": "<agent-id>", "match": { "channel": "feishu", "accountId": "main", "peer": { "kind": "group", "id": "oc_xxx" } } } ``` ## Safety and Rollback - Never delete agents unless explicitly requested. - Before changing `bindings`, capture current `bindings` snapshot. - If wrong route is applied, revert to previous binding set and re-validate. - Prefer reversible, explicit changes and post-change verification. ## Why It Still Routes to `main` - Binding did not match the real incoming `peer.id` (most common). - `bindings[]` was written but gateway runtime did not reload the latest config. - `match.accountId` mismatched current Feishu account key. - Target agent exists but `agents.list[]` entry is malformed (missing required fields such as `identity` object expected by your convention). - Message arrived in a different conversation than the configured group. ## References - Command examples and rollback snippets: [commands.md](./references/commands.md) - Chinese runbook and confirmation checklist: [usage-zh.md](./references/usage-zh.md) - Auto-check script: [validate_feishu_bindings.py](./scripts/validate_feishu_bindings.py)