CLAWPOD ENGINEERING

Finding, Delegating, and Deleting Agent Secrets

A practical guide to the current security boundaries around discovery, use, rotation, delegation, deletion, ownership, sessions, and audit data.

ClawPod Engineering · 10min read
REVIEWED BYEditorial Review · Security Review
A workbench managing an encrypted store and a short-lived delegation path between metadata cards and a runtime tool

Putting API keys, tokens, or passwords in ordinary memory (MEMORY.md), working documents, or issues can spread values through search and collaboration. Memory Secrets separate a protected value from its searchable description, let the agent select a pointer instead of copying the value, and let the runtime resolve or inject it only for an approved action.

This is a practical guide to the current OpenClaw runtime contract. Tool availability and protected-input methods vary by deployment, so confirm the operator-approved path first.

1. Understand the Memory Secret and its catalog

The protected store holds the credential value. The catalog and search results expose value-free metadata. Record even a pointer in ordinary memory only when necessary, and do not record the value there.

Field Purpose
label Human-readable name
service, host Product and destination
account Account that owns the credential
kind, status Type, such as token or password, and lifecycle state
pointerId Identifier used instead of copying the value
description, purpose Operational context and documented intent

Metadata may be visible in the catalog, search, or prompt context. Do not put passwords, tokens, or recovery codes in metadata fields.

flowchart TD
  I[Approved protected<br/>input path] --> S[Protected<br/>memory-secret store]
  S --> M[Value-free metadata<br/>catalog and search]
  M --> P[Select the exact pointer]
  P --> R{Who needs it?}
  R -->|Owner session| U[Immediate resolve or<br/>runtime injection]
  R -->|Child session| G[Session-bound<br/>limited grant]
  G --> U
  U --> T[Target tool or service]
  T --> V[Verify result<br/>then revoke]
  linkStyle default fill:none,stroke:#64748b,stroke-width:1.5px

2. Map the seven tools

Tool When to use it
memory_secret Store a new protected value with structured metadata
memory_secret_search Find an existing item by label, service, host, account, or kind
memory_secret_get Resolve a value for an immediate tool call in an authorized session
memory_secret_update Rotate a value or correct metadata on an existing pointer
memory_secret_dedupe Collapse eligible historical duplicates with exactly matching values
memory_secret_delete Permanently delete an owner Agent’s pointer and grants from the current store
memory_secret_delegate Create or revoke a pointer grant for a child session

Catalog and search are discovery. Get and runtime injection are use. Keep values out of discovery results, and do not copy a resolved value into output, ordinary memory, prompts, or reports.

3. Store safely and search first

  1. Inspect the <available_memory_secrets> catalog for the service, host, and account.
  2. If it is not visible, use memory_secret_search across label, service, host, account, and kind.
  3. Only then determine whether a new credential is required.
  4. Put non-secret metadata, not the value, in the natural-language request.
  5. Enter the value only through an operator-approved protected-input path. Do not put it in ordinary chat, documents, issues, examples, logs, or shell history.
  6. Verify only the returned safe pointer metadata.

A safe request looks like this:

“Store an API token for the operator@example.com account on example-service. Host is api.example.test, kind is api-token, and status is current. I will provide the value through <ENTER_IN_APPROVED_PROTECTED_INPUT>. Do not print the value in the conversation.”

In documentation and tests, use an unmistakable marker such as TEST_ONLY_NOT_A_REAL_SECRET. If the approved protected-input path is unclear, do not accept or store the value until the operator confirms it.

4. Rotate with update, not another store

When a value changes, find the existing pointer and rotate it with memory_secret_update. Named fields such as service, account, host, and kind merge into existing metadata. A raw metadata map can replace the entire map and drop omitted entries, so prefer named fields.

“Find the example-service / operator@example.com pointer and rotate its value. Receive the new value through <ENTER_IN_APPROVED_PROTECTED_INPUT>, keep the existing pointerId, and report only safe metadata.”

Pre-rotation and post-rotation values are distinct. Dedupe does not arbitrarily merge them.

5. Make deduplication a core lifecycle task

Storing the same value under the same service/account in the same session may reuse the existing pointer. For historical duplicates, memory_secret_dedupe compares exact values. Similar names alone are not enough to merge entries.

The preservation rules are:

  • Keep the newest pointer in an exact-value duplicate group.
  • Preserve a pointer with an active delegation so child work is not interrupted.
  • Preserve the same value as a separate credential when service or account differs.
  • Leave distinct and rotated values untouched.

Dedupe applies only to the owner Agent’s store. Review catalog/search results first. Afterward, report only kept and removed pointer IDs, not values.

Preview: “Show duplicate candidates using only service/account and pointerId. Do not change anything yet.”

Execute: “Apply the preservation rules and deduplicate my memory-secret store. Report only the kept and removed pointerIds.”

6. Delete carefully and clean up legacy tombstones

memory_secret_delete physically removes an owner Agent’s pointer and its delegations from the current memory-secret store. The same owner Agent can delete a pointer created in an earlier session. The tool cannot recover it from the current store. This does not remove copies in backups, snapshots, input channels, or external services.

List the candidate and dependent work first.

Preview: “Show retirement candidates for example-service using only pointerId and metadata. Do not delete anything.”

Confirmed execution: “Hard-delete the reviewed pointer <POINTER_ID_FROM_CATALOG> from the current store. State that related delegations are removed, and do not print the value.”

Legacy tombstones from an earlier soft-delete format can be cleaned during a later store write. Do not edit store files or run an improvised purge. Normal pointer deletion and legacy tombstone cleanup are separate concepts.

7. Delegate a grant to a child, not a value

An owner-encrypted msp_... pointer is not useful to an independent Agent, and you should not send it there. For an actual child session created by the parent:

  1. Create the child first and capture the exact returned childSessionKey.
  2. Create a grant with pointerId + childSessionKey.
  3. A simple grant lasts for the child session. Use ttlSeconds for a shorter window, and the advanced childRunId option only when it must bind to one run.
  4. The child resolves through memory_secret_get or runtime injection in its authorized session. The parent does not place the value in a message.
  5. After verifying the result, revoke with revokeDelegationId. Deleting the secret also removes its delegations.

purpose and allowedTargets are advisory documentation, not enforced access controls. Writing “deployment only” does not make the runtime block another target. Effective boundaries come from child session/run binding, TTL, revocation, and target-tool permissions.

Delegate: “Grant <POINTER_ID_FROM_CATALOG> to the child session <EXACT_CHILD_SESSION_KEY> for 15 minutes. Do not send the value in a message; report only the delegation ID.”

Revoke: “The result is verified. Revoke delegation <DELEGATION_ID> and report only its status.”

8. How to use Memory Secrets well

Good usage requires two perspectives at once. The operator or user provides enough value-free context for the Agent to find and maintain the same credential. The Agent starts with the catalog and metadata, then handles the actual value only through an approved protected path and within the runtime boundary that needs it.

Operator perspective: describe the credential context, not its value

  • Specify service, account, host, and kind as precisely as practical. This matters when one service has several accounts or one identity is used on several hosts.
  • Ask the Agent to search the catalog and metadata first instead of saying only “store this.”
  • When the value changes, ask it to update or rotate the pointer it found rather than storing another copy. This preserves the existing reference and lifecycle.
  • Before dedupe, ask for the merge candidates and preservation cases. Before delete, ask for the exact pointer and active delegations.
  • Hard delete irreversibly removes that owner-Agent record and its active delegations from the current protected store. It does not mean backups or external copies are deleted. Review the scope and confirm explicitly.
  • Enter an actual credential value only through a protected-input or secret-storage path approved by the deployment operator. Do not put it in ordinary chat, documentation, issues, logs, or source code.

Use a labeled context block like this in an ordinary message, with no actual value:

[Credential metadata — documentation-only]
Title: <HUMAN_READABLE_LABEL>
URL: https://service.example.com/path
Host: service.example.com
Email: operator@example.com
Account: <ACCOUNT_OR_USERNAME>
ID: <OPTIONAL_NON_SECRET_ID>
kind: <password|token|api-key|oauth|email|credential>
service: <SERVICE_NAME>
description: <NON_SECRET_PURPOSE_AND_SCOPE>
value: <ENTER_ONLY_THROUGH_APPROVED_PROTECTED_INPUT>

Request: Search the catalog and metadata first. If this credential exists, update/rotate that pointer instead of storing another copy.

The value row is not a place to paste the value. It is a label that says separate protected input is required. Supply the actual value through the approved path, separate from this block.

Map the context block to structured fields

Block item Structured field Mapping rule
Title label A short name that distinguishes the record in a list. Do not include the value or part of a token.
URL primarily host, optionally description Normalize the hostname into host. Put non-secret path context in description only when needed. Do not put credentials in a query or fragment.
Host host A server IP or hostname. Documentation examples use reserved IP space or subdomains of example.com.
Email account Use when an email address is the service login identity.
Account account The identity that uses the service, such as a username, bot handle, or tenant account.
ID account or description Map a login identity to account; record a non-secret resource ID with its role in description.
kind kind Use a consistent credential type such as password, token, api-key, oauth, email, or credential.
service service Identify the system or vendor, such as Atlassian, SSH, Claude Code, or LiteLLM.
value secret value in the protected store Store only through the approved protected-input or secret-storage path, never in ordinary chat or metadata.
description description or purpose Explain scope and use without a secret value. Do not confuse this with advisory runtime-delegation purpose.

Documentation-only input examples

Every value below is an unmistakable documentation-only placeholder. Do not use it as a credential or replace it with an actual value in an ordinary message.

Atlassian API token

[Credential metadata — documentation-only]
Title: Atlassian API token for documentation workspace
URL: https://example.atlassian.net
Host: example.atlassian.net
Email: docs-operator@example.com
Account: docs-operator@example.com
kind: api-key
service: atlassian
description: Documentation workspace automation
value: <ENTER_ONLY_THROUGH_APPROVED_PROTECTED_INPUT>

SSH server password

[Credential metadata — documentation-only]
Title: Example staging SSH credential
Host: 192.0.2.44
Account: deploy-example
kind: password
service: ssh
description: Documentation-only staging host in TEST-NET-1
value: <ENTER_ONLY_THROUGH_APPROVED_PROTECTED_INPUT>

Claude setup token

[Credential metadata — documentation-only]
Title: Claude Code setup token for example operator
Host: console.example.com
Account: claude-operator@example.com
kind: oauth
service: Claude Code
description: Documentation-only CLI onboarding
value: <ENTER_ONLY_THROUGH_APPROVED_PROTECTED_INPUT>

LiteLLM host SSH key or password

[Credential metadata — documentation-only]
Title: LiteLLM example host SSH credential
URL: https://litellm.example.com
Host: 198.51.100.27
Account: litellm-admin-example
kind: credential
service: litellm-ssh
description: Documentation-only administration of the example LiteLLM host
value: <ENTER_ONLY_THROUGH_APPROVED_PROTECTED_INPUT>

Portal login

[Credential metadata — documentation-only]
Title: Example customer portal login
URL: https://portal.example.com/login
Host: portal.example.com
Email: portal-user@example.com
Account: portal-user@example.com
ID: customer-example-001
kind: password
service: example-portal
description: Documentation-only portal login; ID is a non-secret resource identifier
value: <ENTER_ONLY_THROUGH_APPROVED_PROTECTED_INPUT>

Agent perspective: start with the catalog and close the lifecycle

  1. Catalog first: Inspect the available safe catalog metadata for a candidate matching service, account, host, and kind.
  2. Search before declaring missing: If the catalog has no clear match, run memory_secret_search with the same metadata. Only after an empty search should you ask whether a new credential is required.
  3. Save with structure: For a new value, populate label, service, account, host, kind, status, and purpose consistently. Never place the value or a fragment of it in metadata.
  4. Rotate by update: When the value or context changes, rotate the owner Agent’s existing pointer with memory_secret_update. Prefer named fields because the raw metadata map replaces the whole map.
  5. Dedupe without crossing identity boundaries: Consider only exact-value duplicates. Keep the newest pointer, but preserve a pointer with an active delegation. Keep the same value separate when service/account differs, and leave distinct or rotated values untouched.
  6. Delete only in the scoped store: Reconfirm the pointer first. Hard delete permanently removes the current owner Agent’s record in the current protected store and its active delegations. Do not claim it deletes backups, external systems, or copies already placed in documents or logs.
  7. Resolve only for immediate use: Resolve a pointer immediately before the runtime tool call, or use runtime injection. Do not output or move the resolved value into a response, ordinary prompt/chat, logs, ordinary memory, reports, files, issues, source code, or a search index.
  8. Delegate narrowly and revoke: Grant the exact childSessionKey of an actual child session. Use a short ttlSeconds when needed, or the advanced childRunId binding for one run. purpose and allowedTargets are advisory documentation, not enforced boundaries. Verify the result, revoke with revokeDelegationId, and do not send an owner-encrypted pointer or value to an independent Agent.

9. Frequently asked questions

Does the catalog or search return the value?

No. Under the tool contract, these operations discover safe metadata and a pointer ID. Metadata can still be visible, so do not put secret values in those fields.

Where should I enter a value?

Use the protected-input path approved by your deployment operator. If no such path is confirmed, do not paste the value into ordinary chat, documents, issues, or shell history.

Will dedupe merge one password used by several services?

It preserves separate credentials when service/account differs. It also preserves pointers with active delegations and leaves distinct or rotated values untouched.

Can I recover a hard-deleted pointer? When do tombstones disappear?

The tool cannot recover it from the current store. A later store write can clean legacy tombstones, while copies outside the store require separate handling.

Does delegation automatically enforce the documented target?

No. purpose and allowedTargets are not enforced policy controls. Use the exact child session, an optional run, a short TTL, explicit revocation, and target-tool permissions together.

Memory Secrets do not guarantee that plaintext disappears from every environment. They provide an operating model: discover with value-free metadata, use an approved protected-input and bounded runtime path, then close the lifecycle with rotation, dedupe, revocation, and deletion.