Handle secrets and sensitive values

Use Portal Credentials for AI model connections. After Agent creation, you can ask the Agent to register work-related secrets in its secret store when the required tools are available and authorized for the task.

Value	Input	Boundary
Anthropic, OpenAI, Codex sign-in or auth.json, Gemini, OpenRouter, local LLM credentials	Admin → Integrations → AI Key Management → Add Key	Tenant-scoped profiles bound to Agents in the same tenant; see credentials
Provider credential entered directly for a new Agent	Creation AI model settings / service authentication	Direct input for that Agent during creation; use a profile for shared rotation and revocation
Signing secret for incoming ClawPod webhooks	Webhooks → Sources	Plaintext may appear only during creation, regeneration, or rotation; see webhooks
Service passwords, API keys, or access tokens needed for Agent work	Ask the created Agent to register them in its secret store	Register only authorized values; use reference IDs rather than storing values in ordinary memory
ClawPod account passwords, MFA codes, recovery codes	Dedicated account security or authentication screens	Use codes for their intended authentication and follow organization recovery-code storage procedures
URLs, project IDs, non-sensitive feature flags	Creation environment variables	Not a secret storage path; see environment variables

Register a secret through Chat after creation

1. Open a dedicated 1:1 Room with the intended Agent.
2. Ask it to register an authorized value, for example:

Register this service credential in your secret store with the label report-service for report retrieval. Do not copy it into ordinary memory or documents. Reply only with registration status and the reference ID, never the value.

3. The Agent uses memory_secret when available. Confirm ok: true and pointer_id in the tool result before treating registration as complete. If the tool is missing or disabled, the Agent should report that instead of claiming success.
4. For later work, refer to the label, purpose, or ID: “Find the report-service secret and use it for the authorized report lookup without displaying its value.” Registration does not automatically configure authentication for every tool.

A value sent through Chat may remain in the original message or processing records. Registering it does not automatically delete or redact earlier Chat history. Use an organization-approved way to provide the value and avoid shared Rooms or repeated messages.

memory_secret_search finds reference metadata; memory_secret_get returns redacted information. Where available, use memory_secret_update and memory_secret_delete for update and deletion requests. Deleting a stored secret does not revoke the original token at its external provider.

Provider credentials

For API keys, issue a credential in the provider's official console; for Codex sign-in, follow the Credential login procedure. Register the provider and type in AI Key Management, bind it only to the intended same-tenant Agents, and test in a small Room. On exposure, departure, or contract termination, issue and apply a replacement and revoke the old value.

The Portal does not reveal stored raw credentials. Replace lost values rather than trying to retrieve them.

Webhook signing secrets

A signing secret verifies incoming requests from a Source; it is separate from provider credentials.

1. Securely store the secret shown when creating the Source.
2. Enter the same value in the external service's webhook settings.
3. If exposure is suspected, rotate or regenerate the Source secret and immediately update the external service.
4. Send a test event to verify the new signature and delivery.

Do not store secrets in ordinary content

Keep secrets out of SOUL.md, AGENTS.md, TOOLS.md, MEMORY.md, shared Chat, Task comments, meeting transcripts, Skill packages, webhook payloads, and custom environment variables. Do not register another user's auth.json, MFA recovery code, or browser cookie. Do not use internal settings or APIs as a vault.

Agent secret store and internal paths

The Agent secret store scopes values to the owning Agent. Tool responses return reference metadata and redacted values rather than plaintext. Its implementation stores data at .openclaw/memory-secrets/memory-secrets.json under the Agent workspace. Use the secret tools instead of editing this file directly.

The Portal's /agents/:id/secrets is a separate internal API for Agent configuration environment variables. It is not the memory_secret store and is not required for Chat-based registration.

Do not repeat registered values in ordinary memory, documents, or replies. Verify work results and success or failure status instead.

External service connections

Resend email uses an API key stored in the Agent secret store. Google Workspace uses a separate browser-based Google authorization flow.