How to implement secrets

[scenic lake]

for discord bot tokens, llm tokens and others for tools such as emails and passwords

[marsh orbit]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[scenic lake]

@slow kayak please tell me what to do

[valid hazel]

@slow kayak a gentle nudge as I have a similar question - where is the best practice way of implementing secrets while keeping them out of reach of agents

[slow kayak]

Best practice: use SecretRefs, not plaintext config, for anything OpenClaw supports — Discord bot tokens, model/API keys, gateway auth token/password, many channel tokens, MCP server env vars, etc.

The important nuance: SecretRefs keep secrets out of openclaw.json / auth profiles and resolve them into the Gateway’s in-memory runtime snapshot. They do not magically make a secret unreachable from every process on the machine if you also give an agent broad exec/filesystem access. So the secure pattern is:

1. Store secrets outside the agent workspace:

   • env var refs for simple setups
   • file provider for a locked-down ~/.openclaw/secrets.json
   • exec provider for 1Password / Vault / sops / custom resolver

2. Reference them in config, e.g. Discord token:

channels: {
  discord: {
    token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" }
  }
}

3. Don’t expose the same secret source to agents:
   • don’t put secrets in the workspace, AGENTS.md, memory, or MCP config as plaintext
   • don’t allow agent file-read access to your secret files
   • don’t pass secret env vars into arbitrary tools/subprocesses unless required
   • keep exec restricted/approved/allowlisted if agents can run shell commands

For stronger isolation, I’d use an exec SecretRef backed by 1Password/Vault/sops, so OpenClaw can resolve the credential during activation but the agent doesn’t get a convenient env var or plaintext file to read.

Docs:
https://docs.openclaw.ai/gateway/secrets
https://docs.openclaw.ai/reference/secretref-credential-surface

[scenic lake]

Thanks. And what about other secrets? Such as emails and passwords?

Like i wanna make a workflow where agents need login info on a website. @slow kayak

[slow kayak]

For website logins, the safest answer is: don’t hand the agent the email/password at all.

Recommended pattern:

1. Use the dedicated openclaw browser profile.
2. You manually log into the site once — ideally with your password manager/passkey/2FA.
3. The agent uses the already-authenticated browser session/cookies for the workflow.

That keeps the actual password out of prompts, logs, memory, tool args, and screenshots. It also avoids bot-detection weirdness from scripted login forms.

What I would not do:

• put website passwords in AGENTS.md, memory, .env, or workflow prompts
• ask the agent to type your password
• store personal primary-account creds in a file the agent can read
• rely on SecretRefs as a generic “website password vault” and then expose them to browser actions — if the agent can retrieve/type the password, it can potentially leak it

If the workflow truly needs repeatable auth without a human around, best practice is usually one of these:

• Create a dedicated low-privilege account for the agent, not your main account.
• Prefer API tokens/OAuth app credentials over human passwords where the site supports it.
• Store those tokens using SecretRefs if they are for supported OpenClaw credential surfaces, or behind a custom exec/vault-backed tool that performs one narrow action and never returns the secret.
• Keep permissions scoped: “can upload invoice” is better than “full admin account”.

Important limitation: once an agent controls a logged-in browser, it can still act as that logged-in user and may see pages/account data. So the secret can be hidden, but the authority of the session is still delegated. Treat logged-in browser profiles like a capability, not just a convenience.

Docs:
https://docs.openclaw.ai/tools/browser-login
https://docs.openclaw.ai/tools/browser
https://docs.openclaw.ai/gateway/secrets