Smithery CLI 认证体系深度指南:OAuth 登录与 --policy 受限 Token 的安全实践
Smithery CLI 认证体系深度指南:OAuth 登录与 --policy 受限 Token 的安全实践
Smithery CLI 是连接 AI Agent 与 10 万+ MCP 工具和技能的命令行工具,而认证是它安全体系的第一道闸门。本文围绕两条主线展开:一次完整的 smithery auth login OAuth 浏览器登录,以及一组 --policy 受限 Token 的最小权限实战,帮助你从"能登录"进阶到"用得好、守得住"。
Smithery CLI 认证的两层凭证设计
在动手之前,先理解 Smithery CLI 认证体系的两层凭证结构,后面所有内容都是围绕它们展开的:
| 维度 | 个人 API Key | 受限服务 Token |
|---|---|---|
| 获取方式 | smithery auth login(OAuth 浏览器授权) |
smithery auth token --policy '<json>' |
| 权限范围 | 账号全量权限 | 由 policy 约束精确限定 |
| 生命周期 | 长期有效 | 默认 1 小时,最长 24 小时 |
| 适用场景 | 本机日常开发、发布 MCP | 浏览器、移动端、Agent、CI 等受限环境 |
🔐 核心原则:永远不要把完整的 API Key 交给不可信代码——浏览器插件、移动端、自动化 Agent 应只拿到按需铸造的受限 Token。
OAuth 登录四步流程:smithery auth login 全解析
确认已安装(npm install -g smithery@latest,要求 Node.js 20+)后,只需一条命令启动认证:
smithery auth login
CLI 会在终端完成四步操作,源码实现见 src/lib/cli-auth.ts:
- 创建认证会话:向 Smithery 认证服务请求一个一次性
sessionId和授权 URL(createAuthSession); - 自动打开浏览器:按平台选择
open(macOS)、start(Windows)、xdg-open(Linux)打开授权页,打开失败时终端会直接打印 URL 供手动访问(openBrowserForAuth); - 轮询等待授权:每 2 秒轮询一次授权状态,最长等待 5 分钟;遇到 5xx 或网络抖动会自动退避重试最多 3 次(pollForApiKey);
- 校验并持久化:拿到 API Key 后先发一次轻量请求验证密钥有效(validateApiKey),再连同组织、命名空间一起写入本地配置。
成功后终端会打印 ✓ Successfully logged in 及当前 Organization / Namespace,即可正常使用 mcp、tool、namespace 等所有命令。
多组织用户怎么选组织?
如果你的 Smithery 账号属于多个组织(基于 WorkOS),轮询到 organization_selection_required 状态时,终端会交互式列出组织供你选择;非交互环境则应直接传参指定:
smithery auth login --organization <organization-id>
组织 ID 会被附加到授权 URL 的 organization_id 查询参数中(withOrganizationInAuthUrl),避免登录过程中反复选择。
Agent 与无浏览器环境
在脚本或 AI Agent 的非 TTY 环境中执行 smithery auth login 时,CLI 不会打印交互文案,而是直接输出一段机器可读的 JSON(含 auth_url 与 session_id),由上层程序把授权链接交给人类用户点击完成(非 TTY 分支)。这让"人类点链接、Agent 等结果"的协作流程成为可能。
Token 存哪里、怎么安全查看
登录成功后,API Key 与命名空间、组织信息一起保存在跨平台配置目录的 settings.json 中,路径逻辑见 getSettingsPath:
| 操作系统 | 配置目录 |
|---|---|
| Linux | ~/.config/smithery/ |
| macOS | ~/Library/Application Support/smithery/ |
| Windows | %APPDATA%/smithery/ |
如果这些目录不可写,可通过环境变量 SMITHERY_CONFIG_PATH 指定自定义路径。
环境变量优先:读取凭证时,SMITHERY_API_KEY 环境变量的优先级高于本地配置(getApiKey)。这意味着在 CI/CD 中只需注入变量即可认证,无需登录态。
查看当前凭证推荐使用脱敏输出:
smithery auth whoami # 仅显示前 8 位 + 后 4 位
smithery auth whoami --full # 打印完整 SMITHERY_API_KEY,慎用
不再需要时执行 smithery auth logout,它会清空 API Key、命名空间、组织信息,并连同系统钥匙串中缓存的服务器配置一并移除(handleLogout),公共机器上尤其建议养成习惯。
--policy 受限 Token 六字段速查
命令入口定义在 src/index.ts,约束 Schema 由 Zod 严格校验(ConstraintSchema),字段写错会在本地立即报错,不会把非法策略发到服务端。
| 字段 | 可取值 | 作用 | 示例 |
|---|---|---|---|
resources |
connections / servers / namespaces / skills |
限定可访问的资源类型 | "connections" |
operations |
read / write / execute |
限定允许的操作 | ["read","execute"] |
namespaces |
命名空间 slug(单个或数组) | 把 Token 限定在某个工作空间 | "prod" |
ttl |
秒数或 "1h" / "30m" / "20s" |
有效期,最长 24 小时,默认 1 小时 | "30m" |
metadata |
键值对 | 按元数据过滤连接,实现按用户/团队隔离 | {"userId":"alice"} |
rpcReqMatch |
点路径 → 正则 | 限定 MCP JSON-RPC 请求(实验性) | {"method":"tools/call"} |
AND 与 OR 的两条心智规则
官方技能文档 skills/smithery-ai-cli/SKILL.md 中给出了清晰的心智模型:
- 单个约束内的多个字段是 AND——字段越多,权限越窄;
- 列表与多个
--policy之间是 OR——条目越多,权限越宽。
metadata 同理:单个对象要求所有键值对全部匹配(AND),数组则是"满足任意一个对象"(OR-of-AND),例如 [{"userId":"alice"},{"team":"backend"}] 两者满足其一即可访问。
三个可直接套用的策略模板
⚡ 模板一:只读排查(30 分钟过期)
smithery auth token --policy '{"resources":"connections","operations":"read","ttl":"30m"}'
⚡ 模板二:按用户隔离的执行 Token——多租户场景下,每个终端用户只拿到能操作自己连接的凭证:
smithery auth token --policy '{"namespaces":"my-app","resources":"connections","operations":["read","execute"],"metadata":{"userId":"user-123"},"ttl":"1h"}'
⚡ 模板三:指定连接 + 限定工具(rpcReqMatch)——注意连接 ID 不在 JSON-RPC 请求体里,要用 metadata 限定连接、再用 rpcReqMatch 限定工具:
smithery auth token --policy '{"resources":"connections","operations":"execute","metadata":{"connectionId":"my-github"},"rpcReqMatch":{"method":"tools/call","params.name":"^issues\\."},"ttl":"30m"}'
铸造成功后输出 token 与 expiresAt,并附带提示:设置 SMITHERY_API_KEY=<token> 即可让 CLI 使用该受限凭证(createToken)。忘了字段怎么写?直接运行 smithery auth token --help 查看完整 JSON Schema。
认证安全实践清单
- ✅ 本地开发用
auth login,受限环境一律用--policy铸造短 TTL Token; - ✅ 遵循最小权限:只给
read就别给write,只操作一个命名空间就别留空; - ✅ CI/CD 中通过
SMITHERY_API_KEY环境变量注入,避免落盘登录态; - ✅ 共享机器用完即
auth logout,它会同时清理钥匙串缓存; - ✅ 打印 Token 前确认场合,
whoami --full只在自己屏幕前使用; - ✅ policy 传错时看本地报错即可,
--help里有权威 Schema,不必反复试错。
常见认证报错速查表
| 报错信息 | 常见原因 | 解决办法 |
|---|---|---|
Session expired. Please run 'smithery login' again. |
授权会话超时 | 重新执行 smithery auth login |
Authentication timed out after 5 minutes |
5 分钟内未完成浏览器授权 | 重新登录并尽快在浏览器确认 |
No token found |
本机尚未登录 | 执行 smithery auth login |
Invalid JSON in --policy |
policy 不是合法 JSON 对象 | 检查引号转义;多条策略请重复使用 --policy,不要传数组 |
Invalid policy constraint |
字段不符合 Schema | 运行 smithery auth token --help 对照修正 |
| 保存配置失败(Permission denied) | 配置目录无写权限 | 授予目录权限,或用 SMITHERY_CONFIG_PATH 换路径 |
掌握 smithery auth login 的 OAuth 流程与 --policy 六字段策略模型后,你既能让日常开发登录无忧,也能为浏览器、Agent、流水线铸造"刚好够用"的受限凭证——这正是 Smithery CLI 认证体系"简单登录、精细授权"的设计初衷。