auth-management

name	auth-management
description	认证提供商全链路管理：API Key 配置、OAuth 流程、提供商切换与验证。当需要配置新的 AI 模型提供商认证、切换 API Key、执行 OAuth 登录或排查认证问题时使用此技能。
tools	gateway
metadata	{"category":"operations","emoji":"🔑","tree_id":"system/gateway","tree_group":"system","min_tier":"task_write","intent_priority":15,"intent_keywords":{"zh":["API Key","OAuth","提供商切换","登录","认证状态","认证配置","切换模型提供商","重新登录","API密钥","授权"],"en":["authentication","api key","oauth","provider","login","auth state","credentials"]},"scene_hint":"配置模型提供商认证用此→切换默认模型用models-management→排查认证报错用doctor-diagnostics"}

认证管理技能

适用场景

用户需要配置、切换或排查 AI 模型提供商认证时触发。

选择原则

场景	工具/技能
配置/切换模型提供商认证	本技能
查看/切换默认模型	→ models-management
修改完整配置文件	→ system-config
托管模型认证	→ models-management（六、托管模型认证）

一、检查当前认证状态

1.1 查看认证状态

gateway(action="auth.state")

返回：

• authenticated: 是否已认证
• provider: 当前提供商
• profile: 当前 profile ID
• tokenExpiry: Token 过期时间（OAuth 提供商）

1.2 查看已配置的提供商

gateway(action="config.get")

在返回的 config.providers 中查看所有已配置的提供商及其状态。

二、支持的提供商

提供商	认证方式	API Key 前缀	说明
Anthropic	API Key	sk-ant-	Claude 系列模型
OpenAI	API Key / OAuth	sk-	GPT/o 系列模型
GitHub Copilot	OAuth	—	通过 GitHub 账号授权
Copilot Proxy	Token	—	企业代理
Google Gemini	API Key / OAuth	AIza	Gemini 系列模型
Google Antigravity	OAuth	—	Google AI Studio
MiniMax	API Key	—	MiniMax 模型
xAI	API Key	xai-	Grok 系列模型
Qwen Portal	API Key	sk-	通义千问
插件提供商	OAuth / API Key	—	通过插件扩展

三、API Key 配置链路

3.1 标准 API Key 方式

1. 读取当前配置：

gateway(action="config.get") → 记录 hash

2. 写入 API Key：

gateway(action="config.patch", baseHash="<hash>", patch='{"providers":{"<provider>":{"apiKey":"<key>"}}}')

3. 验证配置生效：

gateway(action="models.list") → 确认新提供商的模型已出现

3.2 API Key 格式验证

提供商	格式要求
Anthropic	以 sk-ant- 开头
OpenAI	以 sk- 开头，不以 sk-ant- 开头
xAI	以 xai- 开头
Google Gemini	以 AIza 开头

警告：不要在日志或回复中展示完整 API Key，只展示前 8 字符 + ...

四、OAuth 配置链路

4.1 启动 OAuth 流程

gateway(action="auth.login.start", provider="<provider>")

返回：

• authURL: 用户需要在浏览器中打开的认证 URL
• state: OAuth state 参数

4.2 完成认证交换

用户在浏览器完成认证后：

gateway(action="auth.login.exchange", code="<authorization_code>")

4.3 OAuth 环境检测

远程/VPS 环境下 OAuth 回调可能无法自动完成，此时：

• 提示用户手动复制 authorization code
• 使用 auth.login.exchange 手动交换

4.4 登出

gateway(action="auth.logout")

五、提供商切换

5.1 切换默认提供商

修改配置中的 defaultProvider 字段：

gateway(action="config.patch", baseHash="<hash>", patch='{"defaultProvider":"<provider>"}')

5.2 多提供商共存

多个提供商可以同时配置。系统按以下优先级选择：

1. 会话/智能体级别的 model 覆盖
2. defaultProvider 指定的提供商
3. 模型回退链中可用的提供商

六、故障排查

常见错误与解决

错误	原因	解决
401 Unauthorized	API Key 无效或过期	重新配置 API Key
403 Forbidden	模型无权限	检查账户权限/配额
models.list 返回空	无有效提供商	配置至少一个提供商
OAuth 回调失败	网络问题或 VPS 环境	手动复制 code 进行 exchange
managed models not configured	托管模型未启用	参见 models-management 托管模型认证

诊断步骤

1. auth.state — 确认认证状态
2. config.get — 查看 providers 配置是否完整
3. models.list — 确认模型列表是否正常加载
4. 如仍有问题 → crabclaw doctor --deep 进行全面诊断

七、安全规则

1. API Key 敏感：config.get 返回的是脱敏后的 Key，不要尝试从其他途径读取明文
2. 不要存储到日志：API Key 和 OAuth Token 不得出现在回复文本中
3. OAuth 环境适配：检测到 VPS/远程环境时，自动切换到手动 code 复制模式
4. 多 profile 隔离：--profile 和 --dev 标志会创建独立的认证存储

八、CLI 命令对照

CLI 命令	等效操作
crabclaw auth	交互式向导（含提供商选择 + API Key/OAuth）
crabclaw onboard --auth-choice <p>	非交互式认证配置
crabclaw configure --sections auth	仅运行认证配置向导
crabclaw doctor --deep	诊断认证问题

九、与其他技能的关系

• models-management: 认证完成后使用 models.list 确认模型可用
• system-config: 认证配置最终写入 config 文件，可通过 config.patch 直接编辑
• auth-management (托管): 托管模型有独立的认证流 (models.auth.*)，详见 models-management