Smithery CLI 认证体系深度指南:OAuth 登录与 --policy 受限 Token 的安全实践

原创2026-10-25 10:47:10464 阅读

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:

  1. 创建认证会话:向 Smithery 认证服务请求一个一次性 sessionId 和授权 URL(createAuthSession);
  2. 自动打开浏览器:按平台选择 open(macOS)、start(Windows)、xdg-open(Linux)打开授权页,打开失败时终端会直接打印 URL 供手动访问(openBrowserForAuth);
  3. 轮询等待授权:每 2 秒轮询一次授权状态,最长等待 5 分钟;遇到 5xx 或网络抖动会自动退避重试最多 3 次(pollForApiKey);
  4. 校验并持久化:拿到 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 认证体系"简单登录、精细授权"的设计初衷。

登录后查看全文
smithery-cli