Agent 鉴权
让凭证停留在 runtime，而不是进入 prompt 循环
agent 的鉴权应该显式、scope-aware，而且尽量无聊。runtime 注入 key，模型只调用工具，失败由确定性的分支处理。
Format: AI-first docs
Source: DocsAgentsAuthPage
注意
模型不应该拥有 secret 管理权。
key 应该属于 runtime 控制的存储和传输层，而不是进入用户可见 prompt 或由模型编写的工具参数。
鉴权职责分层
把职责拆清楚，生产环境里的鉴权才会稳定。
Runtime
负责 key、scope 分配、轮换和传输注入。
- 在模型看到请求前附加 `Authorization` 或 `X-API-Key`。
- 轮换凭证时不需要重写 prompt。
- 保持 staging 和 production 隔离。
Model
负责选择工具，不负责管理 secret。
- 模型应请求能力，而不是请求原始凭证。
- forbidden 不应触发模型猜测式重试。
- 工具输出只暴露安全的失败分类。
Operators
需要足够元信息来排查鉴权问题，但不需要看到 secrets。
- 记录 request id 和 key 身份标签。
- 跟踪每个环境 key 拥有哪些 scopes。
- 把接入失败和产品逻辑失败分开。
在 runtime 边界注入凭证
最干净的模式很简单：模型调用工具，工具适配层附加凭证，API 不依赖任何 prompt 可见 secret。
- 默认优先使用 Bearer auth。
- 新 key 先用 Context API 验证，再构建更深工作流。
- 每个环境边界维护自己的 secret store。
用 scope 表达能力边界
ProfileClaw 的接口是 scope-aware 的，所以 key 也应该和 runtime 被允许执行的工作精确对齐。
- 只读型助手应停留在窄 scope 上。
- prediction、reasoning 和写操作只在必要时提升能力。
- scope 失败应分流到配置修复，而不是交给模型 improvisation。
责任划分
好的鉴权行为来自于堆栈里清晰的所有权。
| 层 | 负责 | 不该负责 |
|---|---|---|
| Runtime adapter | secrets、header 注入、轮换和可重试传输。 | 对话文案或猜测式推理。 |
| Model | 工具选择和工作流意图。 | 原始 key、token refresh 或 scope 修复。 |
| Operations | 环境隔离、审计链路和故障恢复。 | prompt 层凭证处理。 |
决策矩阵
当出现鉴权相关问题时，可以按下面的方式分支。
情况
请求返回 unauthorized
动作
把它视为 runtime 里的凭证缺失、失效或过期。
原因
模型无法修复 secret 边界问题。
情况
请求返回 forbidden
动作
检查 scopes 和 runtime 能力配置。
原因
key 存在，但当前工作流没有该操作权限。
情况
正在接入一个新集成
动作
先用 Context API 验证 key，再扩展到更深调用。
原因
它能用最小可行请求确认鉴权路径已经通。
请求头示例
优先使用 runtime 持有的 Bearer 流，`X-API-Key` 作为备用。
Bearer 请求头
1
curl "https://api.profileclaw.com/api/v1/context" -H "Authorization: Bearer $PROFILECLAW_API_KEY"备用请求头
1
curl "https://api.profileclaw.com/api/v1/context" -H "X-API-Key: $PROFILECLAW_API_KEY"下一步
鉴权稳定后，再去优化请求大小和恢复姿态。