Getting Started with OpenClaw and secr

This is the tutorial version of Securing OpenClaw Agents. If you have an OpenClaw deployment that currently reads API keys from a plaintext config file or a dotenv, you can replace that with a scoped, allowlisted, audited credential broker in about five minutes — with a single plugin install.

This walkthrough assumes you have:

• An OpenClaw runtime installed (openclaw --version works)
• A free secr account — the free tier includes 1 AI agent identity, no credit card
• A few secrets the agent needs to read (an API key, a database URL, etc.)

The @secr/openclaw-plugin is a native OpenClaw plugin: it registers tool-call hooks, message redaction, and the secr.* tools automatically. No SDK glue code is required.

Step 1 — Create a project and an environment

In the secr dashboard, create a project for this OpenClaw deployment. We'll use support-bot as the example. Inside it, there's already a production environment (and development/staging).

Add the secrets your agent needs:

secr secret set SLACK_BOT_TOKEN xoxb-...
secr secret set OPENAI_API_KEY sk-...
secr secret set DB_URL postgres://...

Or paste them into the dashboard. Either works.

Step 2 — Create a scoped agent identity

This is the credential the OpenClaw agent will use. Critically, it isn't a CLI token (that's for humans) — it's an agent identity, with a different prefix and lifecycle.

secr agent create support-bot \
  --project support-bot \
  --env production \
  --permission read \
  --allowlist SLACK_BOT_TOKEN,OPENAI_API_KEY,DB_URL \
  --expires 90d

A few notes on the flags:

• --project + --env: scope the token to one project and one environment. Anything outside that returns 403, no matter what the agent code asks for.
• --permission read: this agent doesn't write secrets. Don't give it permission it doesn't need.
• --allowlist: the comma-separated list of secret keys this agent is allowed to read. If your code later asks for STRIPE_API_KEY, the read fails with a 403, server-side.
• --expires 90d: tokens that live forever are tokens that get forgotten. 90 days is a reasonable default for low-privilege agents.

The CLI prints the token once:

Agent identity created
Token: secr_agent_a1b2c3d4e5f6...

Copy it now — you can't see it again. We're going to put it in a secret store the agent has access to (a Render env var, an AWS Secrets Manager entry, a Kubernetes secret — anywhere except a file on disk you can cat).

Step 3 — Install the plugin

openclaw plugins install npm:@secr/openclaw-plugin
# Or via ClawHub
openclaw plugins install clawhub:secr

That's the entire client install. The plugin registers three hooks automatically when OpenClaw boots:

• before_tool_call — gates outbound tool calls through the secr MCP gateway (allow/deny rules, rate limits, approvals)
• after_tool_call — records each tool call's outcome (success/error + duration) to the audit log
• before_message_write — redacts known secret values from agent messages before they're persisted to the session log

It also exposes the secr.* tools (secr.get, secr.list, secr.materialize) so the agent can resolve secrets on demand.

Step 4 — Bind in IDENTITY.md

Add a secr: block to the YAML frontmatter at the top of your IDENTITY.md. The agent's persona stays where it was; the binding tells @secr/openclaw which project, environment, and (optionally) secr API URL to talk to.

---
secr:
  org: acme
  project: support-bot
  environment: production
---

## Name
SupportBot

## Creature
AI Agent

## Vibe
Helpful and cautious

## Emoji
🤖

The agent token does not go in this file. The whole point is that IDENTITY.md is checkable into source control without leaking credentials. Pass the token via environment variable instead — SECR_AGENT_TOKEN.

Step 5 — Run the agent

export SECR_AGENT_TOKEN=secr_agent_a1b2c3d4e5f6...
openclaw run support-bot

That's it. The plugin:

1. Reads SECR_AGENT_TOKEN from the environment
2. Exchanges it for a short-lived session
3. Resolves any secret the agent asks for via secr.get / secr.materialize, server-side allowlist enforced
4. Pipes every outbound tool call through the MCP gateway
5. Redacts known secret values from agent messages before they hit the session log

You don't import anything. You don't call materializeEnv() yourself. The plugin handles it.

Step 6 — Configure the MCP gateway (optional, recommended)

If your OpenClaw agent invokes tools — github.create_issue, slack.send_message, anything destructive — the plugin's before_tool_call hook routes them through the secr MCP gateway. To gate a specific tool, create a rule in the dashboard.

In Dashboard → MCP Gateway → Rules, add a rule for github.delete_repo:

• Action: require_approval
• Approval timeout: 5 minutes
• Timeout behavior: deny
• Notification: Webhook (Slack/PagerDuty/Discord — see the approval webhooks post) or Telegram for one-tap mobile approval.

When the agent fires github.delete_repo, the plugin pauses the call, the dashboard shows a pending approval, and an admin clicks Approve / Deny (or taps it on Telegram). One-shot grants — each approval consumes exactly once via Postgres FOR UPDATE SKIP LOCKED, so concurrent agents can't double-spend.

You can also create rate-limit rules (max N calls per minute per agent) and outright allow/deny rules with no approval step. All rule types are configured the same way.

Step 7 — Verify

Run your agent. Check the secr dashboard:

• Audit log should show secret reads from the agent identity
• Agent identities page should show support-bot with lastUsedAt recent
• If you wired the gateway, MCP Gateway → Tool Calls should show every tool invocation

If the agent gets forbidden on a secret read, check the allowlist — that's almost always the cause.

What you've actually done

The five-minute version reads like config. What you've actually built is:

• A typed, owned, expiring credential for this agent (not a personal API key)
• A server-enforced allowlist that limits what it can read (not a code-side guard)
• A short-lived session that expires every 30 minutes (not a forever-bearer)
• An audit trail of every secret access and tool call, tied back to the agent identity
• The hooks for tool-level approval workflows when you're ready to use them

Plaintext API keys in IDENTITY.md aren't a tradeoff for speed anymore. The replacement is one openclaw plugins install command.

Advanced: programmatic broker

If you can't use the plugin (custom runtime, embedded use case, non-OpenClaw caller), the same broker is available as a library — @secr/openclaw:

import { OpenClawSecretBroker, loadIdentity } from "@secr/openclaw";

const parsed = await loadIdentity("./IDENTITY.md");
const broker = OpenClawSecretBroker.fromIdentity(parsed);
await broker.materializeEnv();

The plugin uses this same SDK under the hood — every guarantee (allowlist, session lifetime, audit) is identical. You only need this path if you're not running on the OpenClaw runtime.

What's next

• The /agents pillar — threat model + every integration in one place
• OpenClaw plugin reference — install, three hooks, ClawHub listing
• Approval webhooks for OpenClaw agents — Slack, PagerDuty, Discord
• Approve OpenClaw tool calls from Telegram — one-tap inline keyboards
• OpenClaw secret allowlists — when and how to scope credentials tightly
• OpenClaw MCP approval queues — the approval flow end-to-end
• The OpenClaw NHI posture checklist — what good looks like

Or jump straight to creating an account and start with your own deployment — free for 1 agent, no card.