IMesh

Use this skill to operate the IMesh local-first AI-agent mesh from a shell. IMesh uses an asynchronous WebSocket node, HMAC-signed task requests, mDNS peer discovery, streaming task chunks, optional E2EE, and a FastAPI gateway.

Safety rules

• Keep OPENCLAW_WAN_ENABLED=false (the default) unless the operator explicitly requests WAN connectivity.
• Never expose a remote skill unless it is registered with expose_remote=True and the peer is trusted.
• Set OPENCLAW_PSK to a long random shared secret before connecting peers. Both sides must share the exact same value.
• Do not print, copy, log, or commit private keys, API keys, .env files, or the gateway database (*.db).
• Prefer 127.0.0.1 while testing. Ask for explicit operator confirmation before using 0.0.0.0 or any public address.
• When OPENCLAW_AUTH_REQUIRED=true, always pass the Bearer token on execution endpoints.

Common operations

Start a local node

IMesh start --host 127.0.0.1 --port 8765

Discover peers on the local network

IMesh discover

Returns a JSON array of peers with name, host, port, skills, and reachable fields.

Call a skill on a trusted peer

IMesh call local echo \
  --url ws://127.0.0.1:8765 \
  --payload '{"message":"hello"}'

Start the HTTP gateway

IMesh gateway --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000/ in a browser for the interactive portal.

Check gateway health

curl http://127.0.0.1:8000/api/v1/health

List available skills

curl http://127.0.0.1:8000/api/v1/skills

Execute a skill via the gateway

curl -X POST http://127.0.0.1:8000/api/v1/execute \
  -H 'Content-Type: application/json' \
  -d '{"skill": "echo", "payload": {"message": "hello"}}'

Execute via OpenAI-compatible endpoint

curl -X POST http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"openclaw-mesh","messages":[{"role":"user","content":"hello"}]}'

To target a specific skill: add "skill": "skill_name" to the body, or prefix the message with call skill_name.

Identity management

# Generate a new Ed25519 keypair
IMesh keygen
IMesh keygen --output /path/to/identity.pem

# Show the current node identity (public key, name, path)
IMesh identity
IMesh identity --key /path/to/identity.pem

Issue and use an API key

# Issue a new key
curl -X POST http://127.0.0.1:8000/api/v1/checkout/free-key

# Use the key on protected endpoints
curl -X POST http://127.0.0.1:8000/api/v1/execute \
  -H "Authorization: Bearer imesh_..." \
  -H 'Content-Type: application/json' \
  -d '{"skill":"echo","payload":{"msg":"ok"}}'

Configuration

All variables use the OPENCLAW_ prefix. They can be set in the environment or a .env file.

export OPENCLAW_PSK='replace-with-a-long-random-secret'
export OPENCLAW_DEFAULT_PORT=8765
export OPENCLAW_MDNS_ENABLED=true
export OPENCLAW_WAN_ENABLED=false
export OPENCLAW_AUTH_REQUIRED=false          # set true to enforce API keys
export OPENCLAW_GATEWAY_DB_PATH=./openclaw_gateway.db
export OPENCLAW_IDENTITY_KEY_PATH=./.openclaw_identity.pem
export OPENCLAW_PEER_TTL_SECONDS=120

Troubleshooting

Run pytest -q after changing the installation or runtime to verify the full test suite.