OpenClaw 登录与鉴权：获取密钥并填到正确位置

猫仔技术创作者 2026-11-04 157 阅读

OpenClaw 登录与鉴权，是把模型提供商的 API 密钥或 OAuth 凭据交给本机 OpenClaw，让 Gateway 能正常调用模型。

截至 2026-11-01，OpenClaw 官网展示的 macOS、Linux 桌面版版本为 v2026.10.10，Windows 版为 v2026.9.8-1。现在值得重新核对配置，是因为新版安装方式同时覆盖桌面应用、npm 和源码安装，而且旧安装可能仍保留旧版凭据文件；把密钥放错位置时，OpenClaw 本身虽然已经启动，模型请求仍可能失败。下文涉及命令均取自 OpenClaw 官方文档；环境变量优先级和迁移判断属于基于官方存储规则的操作建议。

先分清：OpenClaw 登录不等于模型登录

OpenClaw 是运行在本机、连接聊天应用并执行任务的 AI 助手；模型提供商则是实际处理请求的上游服务。所谓“OpenClaw 登录”，通常不是登录 OpenClaw 官网账号，而是让 OpenClaw 获得 Anthropic、OpenRouter 等提供商的认证凭据。

官方文档把鉴权方式分成三类：

鉴权方式	适合场景	凭据放在哪里	验证命令
API key	常驻 Gateway、服务器、自动化任务	环境变量、`~/.openclaw/.env` 或 onboarding 存储	`openclaw models status`
OAuth	已订阅且提供商允许浏览器授权	每个 Agent 的 SQLite 认证存储	`openclaw models status`
SecretRef	不希望把明文密钥直接写进配置	env、file、exec、store 等 SecretRef 来源	`openclaw models status`

新手优先使用 API key。官方文档明确称它对始终在线的 Gateway 主机“更可预测”。OAuth 虽然可以减少手动复制密钥，但令牌获取、保存和续期多一层流程；如果订阅方式与提供商账户模式不匹配，登录成功也不代表模型请求一定可用。

如果使用桌面版，先按官网的 Quick Start 安装并运行 openclaw onboard。桌面应用会安装 Gateway、聊天界面、设置流程和 Node 运行环境；命令行的 npm 与源码安装路径则应单独执行 onboarding。

获取 API 密钥：去模型提供商控制台创建

第一步是打开准备使用的模型提供商控制台，在其 API key 或 API keys 页面创建一枚新密钥。不同提供商的页面名称不同，不要从搜索引擎里的“示例密钥”页面复制。

创建后通常会看到一串只完整显示一次的秘密值。此时先复制到密码管理器，再执行下面的 onboarding：

openclaw onboard

按照界面提示选择模型提供商，并找到 API key、Provider 或 Authentication 一类选项。把刚才创建的密钥粘贴到密码输入框，不要粘贴到“Base URL”“Model ID”或“Headers”字段。Base URL 是接口地址，Model ID 是模型名称，两者都不是密钥。

不要把真实密钥放进聊天记录、Git 仓库、截图或 issue。仓库虽然提供 .env.example 作为环境变量示例，但真实凭据仍应由本机的秘密管理机制保存。

OpenClaw 官方中文鉴权文档给出的通用环境变量形式是：

export <PROVIDER>_API_KEY="..."

这里的 <PROVIDER> 必须替换成提供商对应的环境变量名称，不是原样输入尖括号。OpenRouter 这类提供商通常使用 OPENROUTER_API_KEY；其他提供商则以其控制台或官方文档规定的变量名为准。变量名写错时，即使密钥内容正确，OpenClaw 也读不到。

手动配置密钥：放到 Gateway 真正读取的位置

如果不想通过 onboarding 保存密钥，可以在启动 Gateway 的那台电脑上设置环境变量。以对应提供商的变量名为例：

export OPENROUTER_API_KEY="你的真实 API 密钥"
openclaw models status

这只对当前终端会话有效。关闭终端或重启进程后，变量可能消失。因此，常驻 Gateway 或由 systemd、launchd 管理的进程，应把密钥放进 ~/.openclaw/.env：

mkdir -p ~/.openclaw
cat >> ~/.openclaw/.env <<'EOF'
OPENROUTER_API_KEY=你的真实 API 密钥
EOF

然后重启 Gateway 进程或对应的守护进程，再执行：

openclaw models status

官方文档列出的环境来源包括 env.shellEnv、~/.openclaw/.env 以及 systemd/launchd。这里最常见的误区不是“少写一个变量”，而是把密钥写到了另一台机器：聊天应用所在电脑保存了密钥，但真正运行 openclaw gateway 的主机没有拿到它。

按官方加载规则核对时，还要注意三个边界。第一，当前 shell 的 export 不等于 .env 文件；第二，.env 放在 ~/.openclaw/，不是项目目录下的任意 .env；第三，修改环境变量后必须重启 Gateway，单纯重开聊天窗口不会刷新守护进程里的旧环境。

OAuth 与手动令牌：别把端点信息塞进认证存储

如果提供商使用 OAuth，运行：

openclaw onboard

在提供商列表中选择对应入口，按浏览器提示完成授权。浏览器返回 OpenClaw 后，不要手工伪造回调地址，也不要把 access token 填进模型名称字段。

需要手动录入令牌时，官方文档给出的执行方式是：

openclaw models auth paste --provider <PROVIDER>

随后在交互提示中粘贴令牌。该方式会把认证信息写入每个 Agent 的 openclaw-agent.sqlite，并同步更新配置。模型端点仍应放在 openclaw.json 或 models.json 的 models.providers.<id> 下，包括 baseUrl、api、模型 ID、请求头和超时；认证存储只负责“用谁证明身份”，不负责定义“请求发到哪里”。

旧版安装中可能仍出现 auth-profiles.json、auth-state.json，或者形如：

{
  "openrouter": {
    "apiKey": "..."
  }
}

不要继续照着旧 JSON 猜字段。官方给出的迁移命令是：

openclaw doctor --fix

Doctor 会把旧凭据导入 SQLite，并在原 JSON 文件旁保留带时间戳的备份。迁移后重新运行 openclaw models status，确认当前使用的认证来源。

常见卡点：装好了、启动了，模型却不可用

密钥放进了 OpenClaw 配置，但认证存储为空

OpenClaw 会从每个 Agent 的 openclaw-agent.sqlite 读取认证配置。新安装应优先运行 openclaw onboard；旧安装则运行 openclaw doctor --fix 导入旧凭据。修完不要只看配置文件是否还存在，认证信息是否成功迁移要看状态命令。

重启后密钥突然失效

先确认密钥写在 Gateway 主机，而不是聊天端；再确认常驻进程读取的是 ~/.openclaw/.env，或 systemd/launchd 实际注入的环境变量。修改后重启 Gateway，再运行：

openclaw doctor
openclaw models status

Doctor 用来检查安装、配置和运行环境；models status 用来查看模型与认证状态。不要用“重新登录网页”代替这两项本机检查。

模型名称填错，但看起来已经登录

认证成功和模型可用是两个状态。认证只证明凭据能通过提供商检查，具体模型仍可能因名称、账户权限或端点配置不可用。遇到“missing provider API key”这类缺少提供商的提示时，先检查变量名和 .env 所在位置；遇到“model not found”或“unknown model”时，再核对 models.providers.<id> 中的模型 ID。官方文档将这类诊断归入 openclaw models status --probe 的凭据资格与原因码，而不是只看聊天窗口是否报错。

旧版认证结构与新版冲突

看到 auth-profiles.json、auth-state.json 或扁平 JSON API key，不要继续手工拼接新字段。运行 openclaw doctor --fix，然后用 openclaw models status 验证。这样既能迁移，也能保留带时间戳的备份，出问题时可以对照新旧文件。

怎么算成功：看状态，不凭感觉

执行：

openclaw models status

看到当前提供商、认证方式和可用模型状态后，再加一项实际探测：

openclaw models status --probe

满足以下可观察结果，才算鉴权真正打通：

openclaw models status 能列出预期提供商，而不是提示缺少凭据。
openclaw models status --probe 能探测目标模型，不再返回凭据缺失或模型不可用原因码。
重启 Gateway 后再次运行状态命令，结果仍然正常，说明密钥进入了正确的持久化位置。
从实际聊天入口发送一条简单测试消息，能够收到模型回复。

如果前三项正常、第四项失败，问题已经从“鉴权配置”转向聊天通道、Gateway 运行状态或具体模型权限；此时应分别检查，不要继续反复粘贴 API key。

官方文档与后续排查入口

完整操作以当前安装版本对应的官方文档为准：

OpenClaw 中文鉴权文档：API key、OAuth、SecretRef、SQLite 认证存储和旧凭据迁移。
OpenClaw 英文鉴权文档：与中文页对照的环境变量加载规则。
OpenClaw Getting Started：安装、首次启动与 Gateway 基础配置。
OpenClaw 官方首页：桌面版、npm、pnpm、installer 与源码安装入口。
OpenClaw 官方仓库：源码、配置目录、CHANGELOG 和 issue 入口。
OpenClaw 官方支持社区：文档入口及后续配置查询。

最省时间的排查顺序是：先跑 openclaw models status，再跑 openclaw models status --probe；有旧凭据就执行 openclaw doctor --fix；密钥则优先通过 openclaw onboard 保存，常驻 Gateway 再检查 ~/.openclaw/.env。这样能把“密钥没拿到”“放错位置”“没有迁移”和“模型本身不可用”四类问题分开处理。

参考来源

身份验证 – OpenClaw (Clawdbot) 文档

# AI # 知识

评论区

0 条评论

登录后可评论。