---
name: secret-mgr
description: Manage OpenClaw agent credentials (usernames/secrets). Use when storing, retrieving, listing, generating, or removing credentials for an agent. Trigger on requests about saving or fetching usernames, passwords, tokens, API keys, or other secrets. MUST call secret-mgr via the pcexec tool.
---

# Secret Manager

## Purpose
Use secret-mgr to store and retrieve agent-scoped credentials (username/secret pairs) and generate secrets.

## Mandatory safety rule
Always invoke secret-mgr through the `pcexec` tool. Do NOT run secret-mgr directly.

## Commands (run via pcexec)

- List keys for current agent
  - `secret-mgr list`
  - Include shared scope: `secret-mgr list --public`

- Get username for a key
  - `secret-mgr get-username --key <key>`
  - Shared scope: `secret-mgr get-username --public --key <key>`

- Get secret for a key
  - `secret-mgr get-secret --key <key>`
  - Shared scope: `secret-mgr get-secret --public --key <key>`

- Set a key entry (username optional)
  - `secret-mgr set --key <key> --secret <secret> [--username <username>]`
  - Shared scope: `secret-mgr set --public --key <key> --secret <secret> [--username <username>]`

- Remove a key entry
  - `secret-mgr unset --key <key>`
  - Shared scope: `secret-mgr unset --public --key <key>`

- Generate a random secret for a key (prints secret)
  - `secret-mgr generate --key <key> [--username <username>]`
  - Shared scope: `secret-mgr generate --public --key <key> [--username <username>]`

- Legacy (hidden) getter
  - `secret-mgr get <key>`

## Usage notes

- Treat all outputs as sensitive. Never echo secrets.
- When the agent needs credentials to access a resource, first try `list` to see if a matching key already exists before asking the user.
- Prefer `generate` when the user wants a new secret or password.
- Use `set` to store both username and secret in one step.
- Use `get-username` and `get-secret` for retrieval.
- Storing can be explicit (user asks) or proactive after the agent successfully registers/creates an account.
- Secrets should be fetched and used immediately in a command, not displayed (e.g., `xxx_cli login --user $(secret-mgr get-username --key some_key) --pass $(secret-mgr get-secret --key some_key)`).

## Examples (pcexec)

- Store credentials
  - pcexec: `secret-mgr set --key github --username alice --secret <secret>`

- Retrieve username
  - pcexec: `secret-mgr get-username --key github`

- Retrieve secret
  - pcexec: `secret-mgr get-secret --key github`

- Generate secret
  - pcexec: `secret-mgr generate --key github`

- Delete entry
  - pcexec: `secret-mgr unset --key github`