{
  "schemaVersion": "1.0",
  "item": {
    "slug": "rotate-openrouter-key",
    "name": "Rotate OpenRouter Key",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/chunhualiao/rotate-openrouter-key",
    "canonicalUrl": "https://clawhub.ai/chunhualiao/rotate-openrouter-key",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/rotate-openrouter-key",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=rotate-openrouter-key",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "CHANGELOG.md",
      "README.md",
      "SKILL.md",
      "references/key-rotation-guide.md",
      "scripts/update-openrouter-key.py",
      "skill.yml"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/rotate-openrouter-key"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/rotate-openrouter-key",
    "agentPageUrl": "https://openagent3.xyz/skills/rotate-openrouter-key/agent",
    "manifestUrl": "https://openagent3.xyz/skills/rotate-openrouter-key/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/rotate-openrouter-key/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Rotate OpenRouter Key",
        "body": "Safely replace the OpenRouter API key across an entire OpenClaw installation, handling all config locations, priority chains, and verification."
      },
      {
        "title": "When to Use",
        "body": "User says \"rotate my openrouter key\" or \"change openrouter key\"\nUser reports 401 errors from OpenRouter\nUser disabled an old key and needs to set a new one\nPeriodic key rotation for security"
      },
      {
        "title": "Key Priority Chain",
        "body": "OpenClaw reads the OpenRouter API key from three sources, highest priority first:\n\n~/.openclaw/.env — environment file, overrides everything\n~/.openclaw/agents/<name>/agent/models.json — per-agent config\n~/.openclaw/openclaw.json — global config\n\nIf a higher-priority source has the old key, updating a lower-priority file has no effect. You must update the key at whichever level it is actually being read from."
      },
      {
        "title": "Step 1: Get the New Key",
        "body": "Ask the user for the new key. It must start with sk-or-v1-.\n\nIf the user doesn't have one yet, direct them to openrouter.ai/keys to generate one."
      },
      {
        "title": "Step 2: Find All Key Locations",
        "body": "# Find every file containing an OpenRouter key\ngrep -r \"sk-or-v1\" ~/.openclaw/ --include=\"*.json\" --include=\".env\" -l 2>/dev/null\n\n# Also check for uncommented key in .env\ngrep -v '^#' ~/.openclaw/.env 2>/dev/null | grep OPENROUTER_API_KEY\n\nReport what you found to the user before making changes."
      },
      {
        "title": "Step 3: Update All Locations and Verify",
        "body": "Run the helper script — it handles both .env and JSON files in one pass:\n\npython3 scripts/update-openrouter-key.py --key \"sk-or-v1-NEW-KEY\" --verify\n\nThe script:\n\nFinds all config files (.env + JSON) containing an openrouter key\nCreates timestamped backups before each write\nUpdates only the key value (minimal change)\nVerifies the new key against the OpenRouter API\nReports what it changed\n\nPreview first with --dry-run:\n\npython3 scripts/update-openrouter-key.py --key \"sk-or-v1-NEW-KEY\" --dry-run"
      },
      {
        "title": "Step 4: Restart Gateway",
        "body": "openclaw gateway restart"
      },
      {
        "title": "Step 5: Remote Hosts (if applicable)",
        "body": "If the user manages OpenClaw on other machines, repeat Steps 2-5 via SSH:\n\nssh <host> \"grep -r 'sk-or-v1' ~/.openclaw/ --include='*.json' --include='.env' -l\"\n\nThen run the update script remotely or copy it over."
      },
      {
        "title": "Step 6: Disable Old Key",
        "body": "Only after verifying the new key works everywhere, tell the user they can now safely disable/delete the old key at openrouter.ai/keys."
      },
      {
        "title": "Scope & Boundaries",
        "body": "Handles: Finding, updating, and verifying OpenRouter API keys in all OpenClaw config locations.\n\nDoes NOT handle: Other provider keys (Anthropic, OpenAI). Key generation (user does that on openrouter.ai). Billing or usage issues."
      },
      {
        "title": "Error Handling",
        "body": "ErrorCauseFix401 after updateMissed a config locationRe-run Step 2 to find remaining old keysKey works in curl but not in bot.env has old key overriding JSONCheck and update .envGateway won't restartUnrelated issueopenclaw gateway stop && openclaw gateway startRemote host still failingForgot to update remote configsSSH in and repeat Steps 2-5"
      },
      {
        "title": "Limitations",
        "body": "Cannot generate or revoke keys (user must do that on openrouter.ai)\nCannot update keys on remote hosts without SSH access\nDoes not handle keys stored outside ~/.openclaw/ (e.g., in systemd environment files)"
      }
    ],
    "body": "Rotate OpenRouter Key\n\nSafely replace the OpenRouter API key across an entire OpenClaw installation, handling all config locations, priority chains, and verification.\n\nWhen to Use\nUser says \"rotate my openrouter key\" or \"change openrouter key\"\nUser reports 401 errors from OpenRouter\nUser disabled an old key and needs to set a new one\nPeriodic key rotation for security\nKey Priority Chain\n\nOpenClaw reads the OpenRouter API key from three sources, highest priority first:\n\n~/.openclaw/.env — environment file, overrides everything\n~/.openclaw/agents/<name>/agent/models.json — per-agent config\n~/.openclaw/openclaw.json — global config\n\nIf a higher-priority source has the old key, updating a lower-priority file has no effect. You must update the key at whichever level it is actually being read from.\n\nWorkflow\nStep 1: Get the New Key\n\nAsk the user for the new key. It must start with sk-or-v1-.\n\nIf the user doesn't have one yet, direct them to openrouter.ai/keys to generate one.\n\nStep 2: Find All Key Locations\n# Find every file containing an OpenRouter key\ngrep -r \"sk-or-v1\" ~/.openclaw/ --include=\"*.json\" --include=\".env\" -l 2>/dev/null\n\n# Also check for uncommented key in .env\ngrep -v '^#' ~/.openclaw/.env 2>/dev/null | grep OPENROUTER_API_KEY\n\n\nReport what you found to the user before making changes.\n\nStep 3: Update All Locations and Verify\n\nRun the helper script — it handles both .env and JSON files in one pass:\n\npython3 scripts/update-openrouter-key.py --key \"sk-or-v1-NEW-KEY\" --verify\n\n\nThe script:\n\nFinds all config files (.env + JSON) containing an openrouter key\nCreates timestamped backups before each write\nUpdates only the key value (minimal change)\nVerifies the new key against the OpenRouter API\nReports what it changed\n\nPreview first with --dry-run:\n\npython3 scripts/update-openrouter-key.py --key \"sk-or-v1-NEW-KEY\" --dry-run\n\nStep 4: Restart Gateway\nopenclaw gateway restart\n\nStep 5: Remote Hosts (if applicable)\n\nIf the user manages OpenClaw on other machines, repeat Steps 2-5 via SSH:\n\nssh <host> \"grep -r 'sk-or-v1' ~/.openclaw/ --include='*.json' --include='.env' -l\"\n\n\nThen run the update script remotely or copy it over.\n\nStep 6: Disable Old Key\n\nOnly after verifying the new key works everywhere, tell the user they can now safely disable/delete the old key at openrouter.ai/keys.\n\nScope & Boundaries\n\nHandles: Finding, updating, and verifying OpenRouter API keys in all OpenClaw config locations.\n\nDoes NOT handle: Other provider keys (Anthropic, OpenAI). Key generation (user does that on openrouter.ai). Billing or usage issues.\n\nError Handling\nError\tCause\tFix\n401 after update\tMissed a config location\tRe-run Step 2 to find remaining old keys\nKey works in curl but not in bot\t.env has old key overriding JSON\tCheck and update .env\nGateway won't restart\tUnrelated issue\topenclaw gateway stop && openclaw gateway start\nRemote host still failing\tForgot to update remote configs\tSSH in and repeat Steps 2-5\nLimitations\nCannot generate or revoke keys (user must do that on openrouter.ai)\nCannot update keys on remote hosts without SSH access\nDoes not handle keys stored outside ~/.openclaw/ (e.g., in systemd environment files)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/chunhualiao/rotate-openrouter-key",
    "publisherUrl": "https://clawhub.ai/chunhualiao/rotate-openrouter-key",
    "owner": "chunhualiao",
    "version": "1.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/rotate-openrouter-key",
    "downloadUrl": "https://openagent3.xyz/downloads/rotate-openrouter-key",
    "agentUrl": "https://openagent3.xyz/skills/rotate-openrouter-key/agent",
    "manifestUrl": "https://openagent3.xyz/skills/rotate-openrouter-key/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/rotate-openrouter-key/agent.md"
  }
}