OpenClaw 登录与鉴权：4 种装法对比，4 步填对 API Key

OpenClaw 装好后并不自带模型，必须自己接一个模型供应商（OAuth 或 API Key），这一步没做完，界面能开但一句话也发不出去。下面按官方文档给出的路径，把”拿钥匙—放对位置—重启—验证”这条链走通。

先分清两件事：装在哪、钥匙放哪

装 OpenClaw 和给 OpenClaw 配鉴权是两件事。官方首页的 Quick Start 只有三行：npm i -g openclaw、openclaw onboard，以及源码方式 git clone https://github.com/openclaw/openclaw.git 后 corepack enable && pnpm install。真正决定你能不能用起来的，是 onboard 之后的那一步——给模型供应商发凭证。这里要注意两条路径的命令不同：OpenClaw 首页 Quick Start 用 openclaw onboard 进入首次引导；而 MiniMax 官方文档写的是安装后若引导没自动弹出，运行 openclaw configure 重新进入配置。两个命令指向的是同一个交互式向导，入口写法以你所看的那家文档为准。

官方鉴权文档把这件事说得很直接：OpenClaw 同时支持 OAuth 和 API key；常驻网关（always-on gateway host）用 API key 最可预测，订阅/OAuth 流也能用，前提是你的供应商账号模型对得上。

这张表的价值在于：常驻部署和随手试用走的是两条不同的配置路径，混用是后面报错的主要来源。

4 种装法怎么选：各有各的坑

官方首页给了 4 类安装入口，版本号是现成的（macOS 与 Linux 桌面版 v2026.10.9，Windows v2026.9.8-1），可以直接对照：

如果你的目的是”尽快验证鉴权通了没有”，用一键脚本或桌面 App；如果之后要接多供应商、写自定义插件，才值得走源码。桌面版还省掉 Node 依赖——官方原文说 apps 会”install Node.js and everything else for you”。

第 1 步：装完先确认 CLI 在手

openclaw onboard

这条命令就是官方推荐的”Meet your lobster”入口，也是所有鉴权配置的挂载点。如果提示找不到命令，说明装的是 App 而不是 npm 包，先确认 PATH 或直接改用 App 内置的引导流程。

第 2 步：拿密钥，去供应商控制台创建

这一步取决于你用哪家模型。以 MiniMax 为例，官方文档给出的流程是：安装后若没有自动进入配置引导，运行 openclaw configure → 选择认证方式（OAuth 登录（推荐） 或 API Key 手动配置）→ 选 Gateway 运行位置（Local，this machine）→ 选要配置的模块（Model）→ 选 Model/auth provider（MiniMax）→ 选 auth method。

选 API Key 分支时，需要你在供应商控制台创建一把订阅 Key 并填进去。各供应商的环境变量名不同：阿里云百炼用 DASHSCOPE_API_KEY，MiniMax 用 MINIMAX_API_KEY，OpenAI 用 OPENAI_API_KEY；具体变量名以各家文档为准，填错位置会导致模型调用失败。阿里云百炼那篇第三方图文教程（中文社区视角）把控制台路径写得很细，可作为参照：百炼首页常用功能区点 API Key → 右上角 创建 API Key → 归属业务空间保持默认、描述填 OpenClaw、权限选 全部 → 确定 → 立刻点 复制 保存那串 sk- 开头的密钥。教程里特别提醒：这一步没及时保存，后面就看不到完整密钥，通常得重建一个。

第 3 步：填到正确位置

这是最容易错的一步。两种填法位置完全不同：

桌面 App 界面路径：右上角 设置 → 左侧 模型配置 → 找到对应供应商（如”阿里云百炼”）→ 粘贴 API Key → 点 测试 → 测试成功后点右上角 保存全部配置。

CLI / 常驻主机路径：官方鉴权文档给的是把它放到运行网关的那台机器上——如果网关跑在 systemd / launchd 下，把 Key 写进 ~/.openclaw/.env，然后重启网关进程。

第 4 步：重启并验证

# 官方文档给出的验证方式
openclaw models status --probe

# 官方文档给出的交互式验证方式
openclaw tui

models status --probe 会按官方定义的”凭据资格 / reason codes”去探测你各个 provider 的凭证状态；openclaw tui 能正常对话，就说明配置成功。MiniMax 文档里的验证口径也是这条：输入 openclaw tui，能正常对话即配置成功。

卡点：报错长什么样、怎么解

进了向导但没配模型：向导里跳过或退出了某一步。解法是重新跑一次进入向导的那条命令（首页 Quick Start 是 openclaw onboard，MiniMax 文档写 openclaw configure），走到 “Select sections to configure” 时选 Model，一路选到对应 provider 的 auth method。

网关读不到 Key：常驻部署下最常见。解法是确认 Key 写在 ~/.openclaw/.env 或当前 shell 的临时导出变量里——官方文档列出了环境变量加载优先级：env.shellEnv、~/.openclaw/.env、systemd/launchd，三种方式都能被网关读到，但 systemd/launchd 管理的网关不继承交互 shell 的环境变量，此时必须把 Key 写进 ~/.openclaw/.env。写完必须重启守护进程，再跑 openclaw models status --probe 复测。

密钥保存时没复制完整：按供应商控制台的说法，完整密钥只在创建后弹出一次，过后看不到。这条属于第三方教程描述的实测路径，解法是回控制台新建一把专门给 OpenClaw 用的 Key，别去猜旧的那串。

OAuth 登录页打不开 / 授权卡住：官方文档给了另一条被认可的路径——Anthropic 侧支持 setup-token，也允许复用本机已有的 Claude CLI 登录态。换一条鉴权路径比反复重试授权更省时间。

怎么算成功

三个可观察信号：其一，openclaw models status --probe 不再报缺凭证的 reason code；其二，openclaw tui 里能正常对话；其三，桌面端 设置 → 模型配置 中点 测试 返回成功，且已点 保存全部配置。第三条最容易被忽略——只测不保存，下次启动照样没配。

顺带一提，OpenClaw 官方首页明确写着”No subscription. No hosted tier. No token.“，意思是这个项目本身不收订阅费也不托管，你用哪家模型、哪家 API key，完全由你自己的供应商账号决定。这也是为什么鉴权这一步必须自己动手。

参考来源

• OpenClaw 官方首页（安装方式、桌面版版本号、更新命令）
• OpenClaw 官方仓库（源码 checkout 方式、pnpm workspace 说明）
• 官方文档 · Authentication（API key 与 ~/.openclaw/.env、重启网关、models status –probe）
• 官方文档 · 平台与安装（Windows / Linux 桌面版入口）
• MiniMax 开放平台文档中心 · OpenClaw（onboard 认证向导各选项、tui 验证）
• 阿里云百炼开发者社区 · OpenClaw 连接百炼图文教程（中文社区视角，密钥创建与界面路径）