openclaw-agent-feishu-onboarding

Create OpenClaw agents and onboard Feishu routing with explicit multi-step confirmations. Use when the user needs to (1) define a new agent role and workspac...

Security Scan

The skill's files and runtime instructions are coherent with its stated purpose (creating OpenClaw agents and binding Feishu peer routes); it operates on local config files, has no installs or external network calls, and requests no credentials.

Purpose & Capability

Name, description, SKILL.md, command examples, and the included Python validator all consistently target creating agents and applying/validating Feishu routing in a local OpenClaw config (openclaw.json). Nothing requested (no env vars, no external services) is disproportionate to that purpose.

Instruction Scope

SKILL.md explicitly instructs reading and writing the local OpenClaw config and running openclaw CLI commands and the included validator; this is expected for the stated task. Note: the skill will read potentially sensitive local config (openclaw.json) — the README warns of this and requires multi-step confirmations before writes.

Install Mechanism

No install spec; this is an instruction-only skill with a small included Python script. Nothing is downloaded or written by an installer, minimizing install-time risk.

Credentials

The skill requests no environment variables or credentials. The validator reads OPENCLAW_CONFIG_PATH (if set) and the local filesystem to access openclaw.json; this is proportional to validating local routing config but means the skill requires access to potentially sensitive local config files.

Persistence & Privilege

The skill is not always-enabled and agents/openai.yaml sets allow_implicit_invocation: false, so it won't be implicitly invoked. It does instruct making persistent changes to local config only after explicit multi-step confirmations — appropriate for the task.

Assessment

This skill appears to do what it claims: read your local openclaw.json, guide interactive confirmations, run openclaw CLI commands, and use the bundled Python validator. Before running it: (1) run in a trusted environment because it reads/writes local config files that may contain sensitive data; (2) back up your openclaw.json (or snapshot bindings) before any write; (3) review the validator script (scripts/validate_feishu_bindings.py) yourself to confirm there are no network calls — it performs only local JSON checks; (4) ensure the openclaw CLI you’ll invoke is the genuine binary you expect; and (5) keep the four-step confirmation protocol and require an explicit human go/no-go before any write operations.

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:

{
  "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:

{
  "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
• Chinese runbook and confirmation checklist: usage-zh.md
• Auto-check script: validate_feishu_bindings.py