认证

OpenClaw 支持 OAuth 和 API 密钥两种方式来连接模型 Provider。如果你用的是 Anthropic 账号,我们推荐使用 API 密钥。如果你是 Claude 订阅用户,可以用 claude setup-token 创建的长期 Token。

完整的 OAuth 流程和存储结构,可以看 /concepts/oauth。

推荐的 Anthropic 配置方式(API 密钥)

如果你直接使用 Anthropic,用 API 密钥就行。

  1. 在 Anthropic Console 创建一个 API 密钥。
  2. 把密钥放到 Gateway 主机上(就是运行 openclaw gateway 的那台机器)。
export ANTHROPIC_API_KEY="..."
openclaw models status
  1. 如果 Gateway 是通过 systemd/launchd 运行的,建议把密钥写到 ~/.openclaw/.env 文件里,这样 Daemon 才能读取:
cat >> ~/.openclaw/.env <<'EOF'
ANTHROPIC_API_KEY=...
EOF

然后重启 Daemon(或者重启 Gateway 进程)并再次检查:

openclaw models status
openclaw doctor

如果你不想自己管理环境变量,可以用引导向导来存储 API 密钥:openclaw onboard。

关于环境变量继承的详细说明(env.shellEnv、~/.openclaw/.env、systemd/launchd),可以看 帮助文档。

Anthropic: setup-token(订阅认证)

对于 Anthropic,推荐的方式是用 API 密钥。如果你用的是 Claude 订阅,也支持 setup-token 流程。在 Gateway 主机上运行:

claude setup-token

然后把 Token 粘贴到 OpenClaw:

openclaw models auth setup-token --provider anthropic

如果 Token 是在另一台机器上创建的,可以手动粘贴:

openclaw models auth paste-token --provider anthropic

如果你看到 Anthropic 报错:

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

那就改用 Anthropic API 密钥。

手动输入 Token(适用于任何 Provider;会写入 auth-profiles.json 并更新配置):

openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter

自动化友好的检查命令(过期/缺失时退出码为 1,即将过期时为 2):

openclaw models status --check

可选的运维脚本(systemd/Termux)文档在这里: /automation/auth-monitoring

claude setup-token 需要交互式 TTY。

检查模型认证状态

openclaw models status
openclaw doctor

控制使用哪个凭证

按 Session(聊天命令)

用 /model <alias-or-id>@<profileId> 可以为当前 Session 指定一个 Provider 凭证(示例 profile id:anthropic:default、anthropic:work)。

用 /model(或 /model list)可以打开简洁的选择器;用 /model status 可以看完整视图(候选项 + 下一个认证 profile,以及配置的 Provider 端点详情)。

按 Agent(CLI 覆盖)

为某个 Agent 设置显式的认证 profile 顺序覆盖(存储在该 Agent 的 auth-profiles.json 中):

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

用 --agent <id> 可以指定某个 Agent;不加这个参数就用默认配置的 Agent。

故障排除

”No credentials found”

如果 Anthropic Token profile 缺失,在 Gateway 主机上运行 claude setup-token,然后再检查:

openclaw models status

Token 即将过期/已过期

运行 openclaw models status 确认哪个 profile 正在过期。如果 profile 缺失,重新运行 claude setup-token 并再次粘贴 Token。

要求

  • Claude Max 或 Pro 订阅(用于 claude setup-token)
  • 已安装 Claude Code CLI(claude 命令可用)