clawmes

Hermes Agent for crypto.

[!WARNING]
Pre-alpha. Do not use real funds. No real-network validation has happened yet, and no third-party security audit has been done. The signing paths are tested with mocks but unverified against live mainnet conditions. Use small testnet amounts only until v1.0. See SECURITY.md for the full threat model and recovery checklist.

Clawmes is a Hermes Agent plugin. Wallets, DEX trading, lending and staking, governance, on-chain automation. Python rewrite of @clawnch/openclaw-crypto targeting Hermes.

45 tools. 27 commands. 14 services. 11 hooks. Runs on Telegram, Discord, Slack, Signal, WhatsApp, iMessage, and LINE.

Quick start

# 1. Install Hermes Agent (see https://github.com/NousResearch/hermes-agent)
# 2. Install clawmes from PyPI:
pip install clawmes
hermes plugins enable clawmes
hermes clawmes init                # interactive setup wizard
hermes                             # start chatting

The hermes clawmes init wizard prompts for wallet mode (WalletConnect / local / Bankr), per-mode setup (project ID / password+mnemonic / API key), and optional API keys for the most-used integrations. It writes everything to ~/.hermes/.env in upsert mode (existing keys preserved).

Alternative: install direct from GitHub

hermes plugins install clawnchdev/clawmes --enable
hermes clawmes init

This skips PyPI and pulls from the latest main. Use it if you want a specific commit or pre-release.

Editable / dev install

git clone https://github.com/clawnchdev/clawmes
cd clawmes
pip install -e ".[dev]"
hermes plugins enable clawmes
hermes clawmes init

Releases publish to PyPI automatically via Trusted Publishing on every v* tag push (no tokens, OIDC verified). See .github/workflows/release.yml.

Tools

Channels

All tools and commands work identically on every channel.

Wallet modes

Spending policies set in natural language:

/policy approve transfers under 0.05 ETH on Base, max 10/hour

Automation

The compound action engine lets users describe multi-step plans in natural language:

• Time triggers — every day at 9am, check ETH price
• Price triggers — when ETH drops below $2000, swap 1 ETH to USDC
• On-chain triggers — when gas is under 10 gwei, execute the pending swap
• Conditionals — if my portfolio is down more than 5%, alert me
• Loops + parallel — DCA $100 into ETH every week for 12 weeks

Plans persist to disk and survive restarts. Managed via /plans, /interrupt_plan. The plan tick loop is driven by Hermes' built-in cron daemon.

Security

• WalletConnect mode: clawmes never holds unencrypted private keys.
• Every write tool gates through readonly check + policy evaluation + delegation execution + ledger record.
• Credential leak detection on every LLM-bound output.
• Prompt-injection-resistance guardrails in SOUL.md.
• Sequential write execution — never queues multiple txs.
• Bounded approvals — exact amounts, never unlimited.
• Outbound HTTP restricted to a curated allowlist.
• Transaction verification — always shows what a tx will do before executing.

CLI subcommands

hermes clawmes init              Interactive setup wizard
hermes clawmes doctor            Diagnostics
hermes clawmes wallet            Wallet status / mode switch
hermes clawmes plans             Plan status / list / cancel
hermes clawmes policy            Policy status / set / clear
hermes clawmes persona reinstall Force-overwrite SOUL.md (with confirm)
hermes clawmes skills install    Copy bundled skills to writable user namespace
hermes clawmes update            pip install -U clawmes + bridge refresh
hermes clawmes version           Show version
hermes clawmes uninstall         Remove from plugins.enabled (state preserved)

Architecture

hermes (the upstream CLI, hermes-agent ≥ 2026.4.x)
  └── PluginManager.discover_and_load()
        └── clawmes.register(ctx)
              ├── 45 tools     (registered via ctx.register_tool, write-gated)
              ├── 27 commands  (registered via ctx.register_command)
              ├── 11 hooks     (pre_tool_call, post_tool_call, pre_llm_call, ...)
              ├── 27 skills    (registered via ctx.register_skill, namespaced clawmes:*)
              ├── CLI subcmds  (registered via ctx.register_cli_command)
              └── 15 services  (start_all() starts background lifecycle)
                    │
                    ├── subprocess: clawmes-wc-bridge   (Node — WalletConnect v2)
                    └── subprocess: clawmes-sa-bridge   (Node — MetaMask Smart Accounts; planned)

Two bundled Node sub-process bridges (clawmes-wc-bridge, clawmes-sa-bridge) handle WalletConnect v2 sign-client and MetaMask Smart Accounts SDK respectively, talking JSON-line RPC over stdio. They install on first plugin load via npm ci against pinned package-lock.json files in the wheel.

Configuration

Required in ~/.hermes/.env:

# LLM (one of these — Hermes' standard)
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=
OPENAI_API_KEY=
NOUS_PORTAL_API_KEY=

# Channel (one of these — Hermes' standard)
TELEGRAM_BOT_TOKEN=
DISCORD_TOKEN=
SLACK_BOT_TOKEN=

# Wallet — pick one mode
WALLETCONNECT_PROJECT_ID=
CLAWMES_LOCAL_KEY_PASSWORD=
BANKR_API_KEY=

Optional (per-tool — features degrade gracefully without their key):

# RPC + explorers
ALCHEMY_API_KEY=
BASESCAN_API_KEY=
ETHERSCAN_API_KEY=
ARBISCAN_API_KEY=
OPTIMISM_ETHERSCAN_API_KEY=
POLYGONSCAN_API_KEY=
CLAWMES_RPC_<chain_id>=  # override per-chain RPC URL

# DEX / bridge aggregators
ZEROX_API_KEY=
LIFI_API_KEY=

# LLM inference gateway (gitlawb opengateway — OpenAI-compatible)
OPENGATEWAY_API_KEY=  # ogw_live_… — recommended; service runs unauthenticated without it
                      # during the gitlawb partnership window (auth optional today)
OPENGATEWAY_MODEL=    # optional default model id sent when callers omit model=

# Market data + analytics
COINGECKO_API_KEY=
HERD_ACCESS_TOKEN=

# Social
NEYNAR_API_KEY=
NEYNAR_SIGNER_UUID=
NOOKPLOT_API_KEY=

# NFT
RESERVOIR_API_KEY=

# Governance
TALLY_API_KEY=

# Specialized
GIZA_API_KEY=         # zkML inference
PAYSPONGE_API_KEY=    # fiat on/off-ramp
LOBSTER_API_KEY=      # privacy pools
MOLTEN_API_KEY=       # X (Twitter) integration
CLAWNX_API_KEY=       # agent-to-agent network
HUMMINGBOT_API_KEY=   # market-making gateway (also: HUMMINGBOT_GATEWAY_URL)
WAYFINDER_API_KEY=    # route optimization

# Token launches (override default contract addresses)
CLAWNCH_LAUNCHPAD_ADDRESS=

The setup wizard (hermes clawmes init) walks through the most-used keys interactively with live validation.

Using OpenGateway as your LLM provider

Clawmes ships under a partnership with gitlawb OpenGateway — an OpenAI-compatible inference gateway that routes a single endpoint across model providers (Xiaomi MiMo, GMI Cloud, more). There are two integration modes; you can use either or both.

Mode 1 — Route the whole Hermes stack through OpenGateway (recommended for most users).

Hermes already supports any OpenAI-compatible endpoint as a "custom" provider. Point it at OpenGateway via hermes model:

$ hermes model
# Pick: "custom endpoint" (or equivalent in your Hermes version)
# Base URL:  https://opengateway.gitlawb.com/v1
# API key:   ogw_live_…   (sign in at https://gitlawb.com/opengateway/dashboard to generate one)
# Model:     mimo-v2.5-pro (or any model OpenGateway routes; check https://opengateway.gitlawb.com/health)

This is config-only — no clawmes code change required. Every LLM call the agent makes (conversation, tool routing, summarization, everything Hermes drives) goes through OpenGateway, with secrets staying server-side. During the gitlawb partnership window the gateway accepts unauthenticated traffic, so you can try it without a key — but auth will become required, so generate one early.

Mode 2 — Targeted LLM calls from clawmes tools (advanced).

Clawmes also ships OpenGatewayService (clawmes/services/opengateway.py) — a service that gives any clawmes tool a first-class LLM client for subtasks outside the main agent loop (intent classification, swap-parameter extraction, governance-proposal summarization, etc). Tools opt in by calling:

from clawmes.services.opengateway import get_opengateway_service

result = get_opengateway_service().chat_completion(
    messages=[{"role": "user", "content": "..."}],
    model="mimo-v2.5-pro",
)
content = result["choices"][0]["message"]["content"]

This is independent from Mode 1 — Mode 2 calls go to OpenGateway regardless of which provider Hermes itself uses. Configure via the OPENGATEWAY_API_KEY / OPENGATEWAY_MODEL env vars above.

Development

git clone https://github.com/clawnchdev/clawmes
cd clawmes
pip install -e ".[dev]"

pytest                            # run tests
ruff check clawmes/               # lint
mypy clawmes/                     # type-check

Adding a tool

# clawmes/tools/my_tool.py
from clawmes.tools.registry import write_tool, register_with_ctx
from clawmes.lib.tool_result import json_result

_SCHEMA = {...}                  # OpenAI function-calling schema

@write_tool(name="my_tool", toolset="clawmes-misc", schema=_SCHEMA, description="…")
def my_tool(args, **kwargs):
    return json_result({...})

def register(ctx):
    register_with_ctx(ctx, my_tool)

Then import and call register(ctx) from clawmes/tools/__init__.py:register_all().

See CONTRIBUTING.md for full guidelines and patterns.

Status

Early development. See CHANGELOG.md for milestone progress and HERMES_PARITY.md for the upstream Hermes API contract.

Tech stack

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

License

MIT — see LICENSE.