lisa-openclaw-setup

name

lisa-openclaw-setup

description

Set up OpenClaw as the chat-surface runtime for this project's staff roles. Verifies the openclaw CLI, the ~/.openclaw/openclaw.json config, a secret provider, and the required gateway capabilities (sessions_spawn, native-reply session scoping, the NO_REPLY sentinel), then writes a lean `openclaw` section to .lisa.config.json. Prerequisite for lisa-openclaw-connect-staff and lisa-openclaw-connect-repo-topic. Use when a project wants its facilitator/specialist staff reachable from Telegram or Slack.

lisa-openclaw-setup

Verify the OpenClaw runtime prerequisites and record a minimal, placeholder-safe pointer in .lisa.config.json so the connect skills have what they need. This skill writes only setup-level pointers — never tokens, channel/topic/group ids, bot handles, or route tables. Those live in ~/.openclaw/openclaw.json (OpenClaw's own machine-local source of truth) and are written by the connect skills, never committed.

This SKILL.md is self-contained and runs identically under Claude Code and Codex. There is no command/argument layer in Codex, so do not rely on one.

What OpenClaw is (so the checks make sense)

OpenClaw is a locally-hosted multi-agent gateway. A CLI (openclaw, usually at ~/.local/bin/openclaw) manages a config file (~/.openclaw/openclaw.json) that defines agents, chat-channel bindings (Telegram groups/topics, Slack channels), and routing. A long-running gateway process delivers chat messages to agents and back. Agents reach other agents internally via sessions_spawn rather than by messaging each other on the chat platform.

Required inputs

Gather (ask only for what is missing):

• platform the project will default to: telegram or slack
• facilitator agent id — the single human-facing "chief of staff" agent id (a staff role id; see the soft dependency below)
• secret provider — how OpenClaw stores bot/app tokens (e.g. the OS keychain, a named secret manager, or 0600 local token files). Capture only its type and a reference, never a value.

Soft dependency on staff roles

The facilitator and specialists are staff roles. A companion plugin (lisa-wiki) scaffolds a staff role's "brain" (a wiki/staff/<id>.md doc page plus a dual-runtime subagent at .claude/agents/<id>.md and .codex/agents/<id>.toml) from a config.staff[] entry. This plugin wires that role to a chat surface — the "body".

If config.staff[] (in .lisa.config.json) has no entries yet, tell the user to define their staff first:

• In Claude Code: run /lisa:add-role <Role> (e.g. /lisa:add-role Chief of Staff).
• In Codex: invoke $lisa-wiki:lisa-wiki-add-role with the role.

Only auto-delegate if that skill is actually available in the active runtime; otherwise just print the exact next step and stop.

Workflow

1. Locate the OpenClaw CLI

Resolve a usable openclaw binary, in order:

1. ~/.local/bin/openclaw
2. openclaw on PATH
3. a path the user supplies

If none is found, stop and tell the user to install OpenClaw and re-run. Record the resolved path for the config's configPath/CLI discovery only if it is non-standard.

2. Verify the config file

Confirm ~/.openclaw/openclaw.json exists and is valid JSON. Do not print token values found inside it. If it is missing, instruct the user to initialize OpenClaw (its own init flow creates the file) before continuing.

3. Verify a secret provider

Confirm a token-storage mechanism is configured. Acceptable: the OpenClaw-configured secret provider, an OS keychain entry, or 0600-permissioned local token files outside the repo. Capture the provider type and a non-secret reference only.

4. Probe required gateway capabilities

The connect skills depend on three OpenClaw behaviors. Probe for them and fail closed (warn loudly, do not silently proceed) if any is missing:

• sessions_spawn — internal agent-to-agent dispatch (how the facilitator consults specialists).
• Native-reply session scoping — a top-level human request seeds a session keyed to its thread root (Slack channel + root thread_ts; Telegram supergroup + forum topic + root message_id), and replies in that thread continue the same session, so concurrent threads don't share short-term context.
• Account-scoped Telegram topic agents — in multi-account Telegram configs, channels.telegram.accounts.<account-id>.groups.<group-id>.topics.<topic-id>.agentId routes group messages as an explicit topic route instead of dropping them as a non-default account fallback.
• NO_REPLY sentinel — after an agent sends a message with the platform message tool, returning exactly NO_REPLY as its assistant final prevents the gateway from posting a duplicate loose message.

Probe via the OpenClaw CLI/version and a non-mutating validate, e.g.:

openclaw --version
openclaw config validate

If a capability cannot be confirmed, record it as an unmet prerequisite. The connect skills must refuse to create routes that would post duplicates or leak cross-thread context.

5. Write the lean config section

Update only the openclaw section of .lisa.config.json. Parse the existing JSON, preserve all other keys and formatting as much as practical, and write structurally (never string-splice). Shape:

{
  "openclaw": {
    "defaultPlatform": "telegram",
    "facilitatorAgentId": "<facilitator-agent-id>",
    "secretProvider": {
      "type": "<secret-provider-type>",
      "ref": "<secret-provider-ref>"
    },
    "configPath": "~/.openclaw/openclaw.json"
  }
}

Rules for this section:

• defaultPlatform: "telegram" or "slack".
• facilitatorAgentId: the default facilitator/chief id only — not per-surface routing.
• secretProvider: a pointer only; never token material.
• configPath: optional; default ~/.openclaw/openclaw.json. Set only for non-standard installs.
• Reject writing tokens, channel ids, topic ids, group ids, Slack thread roots, bot handles, or repo paths here. If the user offers them, decline and explain they belong in ~/.openclaw/openclaw.json.

6. Report

Finish with: resolved CLI path, config-file status, secret-provider type/ref, each capability probe result (pass / warn / unknown), the openclaw section written, and the exact next command/skill (lisa-openclaw-connect-staff or lisa-openclaw-connect-repo-topic).

Related

lisa-openclaw-connect-staff, lisa-openclaw-connect-repo-topic. Staff "brains" come from the lisa-wiki plugin's add-role.