Step-by-Step Fix
1. Locate Your Current API Key Status
Log into the OpenClaw dashboard and navigate to Settings > API Keys. You will see a list of all keys associated with your account. Check that:
- The key you are using shows Active status
- The key belongs to the correct workspace (if you have multiple)
- The permissions assigned to the key include the operations your agent needs (read, write, execute, etc.)
If the key shows Revoked or Expired, you must generate a new one.
2. Generate a New API Key
- In Settings > API Keys, click Generate New Key
- Enter a descriptive name such as
prod-automationorcron-job-2026 - Select the required permission scopes for your use case
- Click Create
- Copy the full key immediately — it is only shown once
OpenClaw API keys begin with oc_ followed by a long alphanumeric string. If you see only a masked version (like oc_••••••••), the full key is no longer retrievable and you must revoke and regenerate.
3. Update Your Environment Variables
On Linux/macOS, set the key for the current session:
export OPENCLAW_API_KEY=oc_your_new_key_here
For persistent configuration, add it to your shell profile (~/.bashrc, ~/.zshrc) or your deployment environment:
# In .env file (ensure this file is in .gitignore)
OPENCLAW_API_KEY=oc_your_new_key_here
On Windows (Command Prompt):
setx OPENCLAW_API_KEY "oc_your_new_key_here"
4. Test the Connection
Run the built-in verification command to confirm the key is valid and accepted:
openclaw whoami
A successful response shows your account email, workspace name, and plan tier. If you see 401 Unauthorized or Invalid API key, the key was copied incorrectly or is not yet active — wait 30 seconds and retry.
5. Check Key Permissions
If whoami succeeds but your agent still fails with permission errors, the key may lack the required scopes. Return to Settings > API Keys, click the key name, and review the permission list. Add any missing scopes (browser tool, bash execution, file system access, git operations) and save. Permission changes take effect immediately without needing a new key.
6. Revoke Compromised Keys
If you accidentally committed an API key to a public repository or shared it, revoke it immediately:
- Go to Settings > API Keys
- Click Revoke next to the exposed key
- Generate a replacement key following steps 2 and 3 above
- Audit your git history and use
git filter-repoor contact GitHub support to remove the exposed secret from history
Why This Happens
OpenClaw API keys are scoped credentials tied to your account and workspace. When you reset your password, change your email, or if OpenClaw detects suspicious activity, all existing keys are invalidated as a security measure. Keys can also silently fail if your subscription lapses — free-tier limitations prevent certain key permission scopes from functioning even if the key itself remains active.
Common Mistakes to Avoid
- Hardcoding keys in source files: Never paste an API key directly into your script or configuration file that gets committed to git. Use environment variables instead.
- Using the same key across all environments: Separate keys for dev/staging/production make rotation safe and prevent a leaked dev key from affecting production.
- Not copying the key at creation: OpenClaw only displays the full key once. If you close the dialog without copying, you must revoke and regenerate — there is no "show key again" option.
- Forgetting to update all locations: If you have multiple services or cron jobs using the same key, update all of them before revoking the old one. A single missed reference will cause failures.
- Ignoring the permissions scope: Generating a key with only read permissions then trying to run write or execute operations will produce cryptic errors that look like authentication failures.
FAQ
Q: Does changing my OpenClaw account password invalidate my API keys?
Yes. Changing your OpenClaw account password invalidates all active API keys as a security measure. This prevents someone who had temporary access to your old credentials from continuing to use existing keys. After a password change, generate new API keys and update all automation environments — your agents will fail with 401 Unauthorized until the keys are replaced.
Q: Can OpenClaw API keys expire automatically, or only when manually revoked?
By default, OpenClaw API keys do not have a built-in expiration date — they remain valid until manually revoked or until a security event (like a password reset) invalidates them. Some enterprise plans may support setting expiration dates on keys as a security policy. Check your Settings > API Keys page for any expiration date shown next to each key. If you want to enforce key rotation, set a calendar reminder to revoke and replace keys every 90 days.
Q: What is the difference between an OpenClaw API key and my Anthropic API key?
These are two completely separate credentials. The OpenClaw API key (starting with oc_) authenticates your requests to the OpenClaw platform — it is used to trigger runs, manage workflows, and access the OpenClaw dashboard programmatically. The Anthropic API key (starting with sk-ant-) is what your OpenClaw agents use internally to call Claude. You need both: OpenClaw for the automation platform, and Anthropic for the AI model access. Losing one does not affect the other.
Q: My agent stopped working and the logs show "401 Unauthorized." Is this an API key issue?
Almost certainly yes. A 401 Unauthorized response from OpenClaw's API means the key is either revoked, does not exist, or was copied incorrectly. Check your environment variable to confirm the key value starts with oc_ and has no extra spaces or line breaks. Compare the first 8 characters of the key with what is shown (masked) in your OpenClaw dashboard under Settings > API Keys. If they do not match, regenerate the key and update your environment variable.
Q: How do I audit which services are using a specific OpenClaw API key?
OpenClaw does not currently provide per-key usage logs in the dashboard. To audit key usage, search your codebase and infrastructure for references to the key value or to the variable name you use (e.g., OPENCLAW_API_KEY). Check your CI/CD pipeline secrets, server environment variables, local .env files, and any third-party integration configs. Maintaining a documented key registry — a private note listing which key is used where — makes this audit much faster.
Related Issues
- OpenClaw 401 invalid API key errors in cron jobs
- OpenClaw agent not starting
- OpenClaw login/auth issues – session expired
- OpenClaw permission denied – no access to tools
Additional FAQ
Q: What is the fastest way to diagnose a login problem? The fastest diagnostic is to open an incognito or private browser window and attempt to sign in there. Incognito windows run without extensions and use fresh cookies, which isolates the two most common causes: a browser extension interfering with authentication, or corrupted session cookies. If login works in incognito, the issue is your main browser profile. If it still fails, the problem is your network, your account, or a platform-side incident.
Related Articles
- OpenClaw login / API key fix
- OpenClaw rate limits affecting runs
- OpenClaw agent not starting
- OpenClaw tool calls failing
Additional FAQ
Q: What is the fastest way to diagnose a login problem? The fastest diagnostic is to open an incognito or private browser window and attempt to sign in there. Incognito windows run without extensions and use fresh cookies, which isolates the two most common causes: a browser extension interfering with authentication, or corrupted session cookies. If login works in incognito, the issue is your main browser profile. If it still fails, the problem is your network, your account, or a platform-side incident.