IV. 认证与安全 - 1. OAuth 与认证
📍 课程位置
阶段 ：IV. 认证与安全
课序 ：第 1 课
前置知识 ：I. 核心架构（Gateway/Agent/Session）
后续课程：IV-2. Authentication
🎯 本课核心问题（你不懂我就这样教你）
你在使用 OpenClaw 时，迟早会遇到这些问题：
- 我在哪里填模型 API Key？填错了会怎样？
- Setup-token / API key / OAuth 到底有什么区别？
- 为什么配置错了 Gateway 可能直接起不来？
- 多 Agent / 多账号时，凭证怎么隔离，才不会串用？
一句话：
认证（Auth）就是"让 OpenClaw 有权限调用外部服务"的一套机制；OAuth 是其中一种更标准、更安全的方式。
🧠 心智模型：认证 = 门禁卡，OAuth = 可回收的临时门禁卡
类比：
- API Key：像一张"万能门禁卡"，丢了就麻烦
- Setup-token：像"办卡时的一次性验证码"，用来换到真正门禁
- OAuth：像"你授权我一段时间进门"，可撤销、可续期、更可控
你要的目标是：
- 能用（可用性）
- 可控（安全）
- 可隔离（多 Agent/多账号）
✅ 验收标准
- 知道三种认证方式（API Key / Setup-token / OAuth）的用途
- 知道凭证存储在哪里
- 知道如何做多 Agent 的凭证隔离
- 知道"认证问题"怎么排查
1) API Key（最常见）
什么时候用
- 你有一个提供商的 key（OpenAI/Anthropic）
- 直接填进去就能用
风险
- key 一旦泄露，可能被刷爆
- 难以精细授权
建议
- key 只放在 OpenClaw 的 credentials 系统里
- 不要到处复制粘贴
- 定期轮换
2) Setup-token（一次性换取真正凭证）
什么时候用
- 某些提供商会给你一个一次性 setup-token
- 你用它换取可长期使用的 key/refresh token
关键点
- setup-token 不是长期凭证
- 用完就应该丢弃
3) OAuth（推荐：可控、可撤销）
什么时候用
- 需要更标准的授权流程
- 希望能撤销授权、自动刷新
- 多账号场景更清晰
为什么更安全
- 你不用把长期 key 暴露给每个地方
- 授权可以撤销
- token 可以自动刷新
📁 凭证存储在哪里？（你必须知道）
OpenClaw 通常会把凭证放在类似这些位置（不同版本可能略有差异，但思想一致）：
~/.openclaw/credentials/：全局/通用凭证~/.openclaw/agents/<agentId>/agent/auth-profiles.json：某个 agent 的认证配置
原则：
- 凭证应该尽量 per-agent 隔离
- 不同 agent 用不同 key/不同 oauth profile
🔐 多 Agent / 多账号：最重要的隔离策略
你要避免这种事故：
- work agent 用了 home 的 key
- 某个 key 被限流导致所有 agent 全挂
推荐做法：
- 多 Agent：work/home 分开 workspace
- 每个 Agent 单独一套 auth profile
- 至少一个跨提供者 failover（上一阶段已讲）
🧪 排障：怎么判断是认证问题？
常见症状：
- 401 / 403
- provider 报 invalid_api_key
- setup-token 过期
- OAuth refresh 失败
排障顺序：
- 看 gateway/agent 日志里 provider 错误
- 检查当前 agent 的 auth profile
- 检查 key 是否被撤销/过期
- 必要时重新授权/轮换 key
⚠️ 常见陷阱
| 陷阱 | 表现 | 原因 | 解决 |
|---|---|---|---|
| 把 setup-token 当长期 key | 用一阵就失效 | setup-token 一次性 | 用 setup-token 换长期凭证 |
| 多 agent 共用一个 key | 一处限流全挂 | 缺少隔离 | per-agent auth profiles |
| key 泄露 | 费用暴涨 | 放进仓库/聊天记录 | 只放 credentials，立即轮换 |
| OAuth 不刷新 | 过期后全部失败 | refresh 流程断 | 重新授权/检查回调配置 |
📝 学习心得
认证这章的核心不是"怎么填 key"，而是"怎么不翻车"：
- 凭证一定要隔离（per-agent）
- setup-token 只是入场券，不是门票
- OAuth 更可控，适合多账号
- 任何认证问题都要能快速定位和回滚
✅ 本课总结（记住 5 句话）
- API Key 最常见，但泄露风险高，要轮换。
- setup-token 是一次性换取真正凭证的"验证码"。
- OAuth 更标准、更可控，可撤销、可刷新。
- 多 Agent 一定要做 per-agent 凭证隔离。
- 认证问题排查：先看日志，再看 auth profile，再轮换/重授。
🔗 相关资源
- 官方 OAuth 文档：https://docs.openclaw.ai/concepts/oauth
- 配置参考：https://docs.openclaw.ai/gateway/configuration-reference
- 下一课：IV-2. Authentication