跳到主要内容
这一页是 Agent 原文

本页由 skills/fnos-cli/reference/oauth.md 自动同步，写给 Agent 的措辞一字未改。第一次上手建议先读5 分钟上手、命令速查表。

OAuth 参考

固定参数​

  • client_id: YJNMPJUGA9
  • scope: trim.user.all trim.file.read trim.file.write trim.download.all trim.appcenter.all trim.photo.all trim.system.all trim.log.all trim.storage.all trim.docker.all；产品专属 scope 见对应 reference
  • code_challenge_method: S256
  • device name/model: trim-cli / CLI
  • 授权 code 有效期：5 分钟

登录​

fnos-cli --profile home --host <host> --port <port> login --authorize-only
fnos-cli --profile home --host <host> --port <port> login --code '<code>'

Agent 默认使用两段式授权，用户不必运行终端：

  1. 确认用户指定的 NAS 和 profile；已有有效 session 时直接复用。新目标未知时先询问。
  2. Agent 执行 login --authorize-only，把返回的 authorization_url 原样作为链接发给用户。 authorization_pending=true 仅代表等待授权，不是已登录；此命令不等待终端输入。
  3. 用户自行打开链接、输入账号密码、确认授权，并把页面显示的一次性 code 发回当前 Agent。
  4. Agent 收到用户明确提供的 code 后，用同一执行主机、系统用户、配置目录、profile 和连接参数 执行 login --code '<code>'。code 作为独立参数传递；使用 shell 时正确引用，不拼接为 shell 语法。
  5. 确认 token_persisted=true、refresh_token_persisted=true，再用同一 profile 执行 system info 等只读请求，成功后才报告已连接并继续用户任务。

Agent 不代填账号密码、不自动点击授权、不读取浏览器页面 code；仅处理用户主动发来的 code。 code 会经过聊天和工具调用记录，也可能在本机进程参数中可见；它是敏感的一次性凭据，不能承诺 聊天侧不留存。不要在回复中复述、额外写文件/日志、开启 shell trace 或转发给其他人。 access/refresh token 和 PKCE verifier 留在 CLI 的存储中，不读取或发送到聊天。 若设备启用安全访问码，token 兑换响应的 x_access_code 也由 CLI 保存在同一 profile 的受控 session 中； Agent 不接收、不复述此值。该响应值已编码，CLI 会原样用作请求头，不再编码。CLI 对后续受保护 HTTP 请求自动附加 X-Access-Code 与 X-Access-Source: app，不发送 x-device-id。浏览器中的访问码页面仍由用户自行完成。

授权 URL 包含 PKCE challenge、client、scope 和 device 参数，不包含 redirect_uri，不要自行 改写。每个 profile 只保留一个 pending verifier；等待 code 期间不要再次生成链接，否则会覆盖 原 pending。两个命令均显式保持相同 host/port/scheme/TLS 选项；新 session 尚未保存时，不能 依赖默认目标。远端明文 HTTP 两步都需要 --scheme http --allow-insecure-http。

目标为已支持的 Connect 设备子域名时，CLI 对目标的 OAuth 和代理 HTTP 请求自动附加 mode=relay Cookie；其他目标不附加。此 Cookie 只用于 CLI 发出的请求， 不改变用户在浏览器中打开的授权链接。

code 只能交换一次，有效期 5 分钟。pending 过期、丢失、目标不匹配或 code 交换失败时停止， 解释原因并重新发起授权，不循环重试旧 code；若响应表明 token 已保存而用户摘要/探测失败， 先检查现有 session 的只读调用，不再次交换已消费的 code。多个并行授权使用不同 profile。 两步都使用 Skill 提供的同包启动器，不需要交互 TTY；切换 Host/SSH/容器时须在实际执行 环境重新授权，不能假定本机 session 自动共享。macOS Keychain 可能需要用户批准系统提示。

用户主动选择手动终端时仍可运行普通 login，在 CLI 提示中输入 code；--no-open 仅关闭 自动打开浏览器，不改变这条手动流程。Agent 默认流程不要求用户打开终端。 trim.basic 不属于当前可申请列表，CLI 不显式申请。旧的 file photo scope 或缺少当前模块 所需 scope 的 session 不再兼容，必须重新登录；refresh token 不能用来扩展原授权范围。

刷新授权​

fnos-cli --profile home login --refresh

命令开始前 access token 在 60 秒内过期会自动 refresh。代理 /ogh/ac/w 或原生 HTTP /ogh/ac/h/* 返回 401 时，CLI 按 profile 加锁 refresh 并只重试一次；第二次仍 401 时停止。 refresh 返回新 refresh token 时替换旧值，未返回时保留旧值。刷新前 CLI 会把当前 session 原值 写回当前 profile，确认真实存储目标可写；预检失败时不会发送 refresh 请求，因此不会消耗可能轮换的 refresh token。 ask-file 的存储选择只会询问一次，并沿用到本次刷新提交。多进程获得锁后会重新读取 session， 已被其他进程刷新时直接使用新 token，不覆盖较新的 session。 refresh 不轮换设备安全码，CLI 在请求中携带已保存的访问码头，并在更新 OAuth token 时保留安全码。 响应带 x-trim-safe-code-challenge 时按设备访问码拦截处理，不触发 OAuth 401 refresh。HTTP 429 表示验证受限，应等待后重试；503 表示验证服务不可用；403 可能是策略拒绝或临时封锁。网关返回 200 挑战页时无法进一步判定原因，CLI 提示重新登录取得有效码。

存储仍可能在请求发出后失效。若 refresh 成功但最终 session 写入失败，不要反复使用旧 refresh token；服务端可能已完成轮换，应重新发起上述 OAuth 授权。

登录状态与退出​

session 保存 access/refresh token、可选设备安全码、过期时间、OAuth client/device/scope 和用户摘要。 logout 清理当前 profile 的 session 和 pending 文件，不承诺远端撤销令牌。

需要重新登录时走上述授权流程，不回退到 CLI 用户名密码、2FA 或旧 token 恢复。只有用户 回传的 code 可用于 login --code；code verifier、access token 和 refresh token 不放进命令参数， 也不输出到聊天或日志。

新版升级​

本产品仅使用 FNOS_CLI_* 配置变量并保存独立登录状态。升级后重新授权；不迁移、读取或删除旧登录数据。其他产品的同名 profile 不共享状态。

自动同步自 skills/fnos-cli/reference/oauth.md（fnos-cli 0.5.1）。请勿直接编辑本页，修改请提交到上游仓库 fnnas-labs/fnos-cli-skill。