跳到主要内容

凭据与鉴权

本页讲解 Anyy 鉴权的两个方面：

  1. 出站 —— Anyy 访问所配置的模型 provider 所用的凭据（API Key， 或某个 provider 账户的“登录”流程），以及这些密钥在磁盘上的存放位置。
  2. 入站 —— 谁被允许访问常驻的网关（gateway）与按需启动的面板 （dashboard）。

provider 是可配置的后端。Anyy 的身份始终是 Anyy；provider 的名称 （以及它若有的登录流程）只是后端标签和一种鉴权方式，绝不是 Anyy 的身份。 关于选择运行哪个模型，参见 配置模型。关于更宏观的信任模型及密钥脱敏方式， 参见安全与隐私。若要首次设置凭据， 初始化向导会逐步引导你完成。

Provider API Key​

向 provider 鉴权的默认方式是 API Key。你通过初始化向导录入：

anyy setup model

向导会依次询问 provider、鉴权方式与默认模型。对于 API Key 类型的 provider，它会把 密钥保存为一个profile 本地密钥文件，并且只把指向该文件的引用写入配置——密钥 本身绝不会出现在 config.yaml 中。

引用通过一个简短的 scheme 前缀，让配置在不内联值的前提下指向某个密钥：

Scheme含义
secret:<path-under-secrets>profile 的 secrets/ 目录下的文件，以其相对路径寻址——可以是 secret:openai-key 这样的纯名称，也可以是 secret:telegram/personal/token 这样的嵌套路径（向导为 API Key 写入的就是这种）
env:<NAME>在使用时解析的环境变量
file:<path>由你自行管理的文件
literal:<value>内联值（真实密钥请勿使用）

对一个已配置密钥的 provider 再次运行 anyy setup model 时，会以掩码形式 打印该密钥，并提供保留、替换或清除的选项：

<provider> API key: sk-...1234... OK
[K]eep / [R]eplace / [C]lear (default K):

Keep（或回车）保持现有引用不变。Replace 会提示输入新密钥。Clear 会将该密钥 排入删除队列——并且由于清除凭据属于安全相关变更，它会显示在 Review Changes 摘要中，仅在你确认后才真正执行。

注意

切勿将 API Key 直接粘贴进对话提示、工具参数或 shell 命令。只有 Anyy 作为 已登记的密钥引用持有的值才受脱敏保护；内联粘贴的密钥可能泄露进日志、审计轨迹 或 provider 报错文本。请始终通过 anyy setup model（或 secret: / env: / file: 引用）录入，使值被存储而非内联。

Claude OAuth​

某个 Anthropic 系列的 provider 后端既可以用普通 API Key 鉴权，也可以通过登录 Claude 账户（Claude Pro/Max）并复用该账户的 OAuth 凭据来鉴权。这纯粹是某一个 provider 的鉴权方式：登录是为该后端获取凭据。它不会使 Anyy 变成 Claude 或 Anthropic，Anyy 也绝不会把 Claude 身份注入到助手中。

在 anyy setup model 中选择该 provider 时，你可在以下两者间选择：

1. Claude Pro/Max subscription (OAuth login)
2. Anthropic API key (pay-per-token)

OAuth 登录（登录流程）。 选择订阅路径会在前台运行该 provider 自己的 setup-token 命令：

claude setup-token

provider 的 CLI 自行掌管浏览器、URL 与粘贴验证码的交互；Anyy 不会解析或回放 其输出。命令返回后，Anyy 按以下顺序查找可用凭据：

  1. Anyy 自己存储的 OAuth 凭据（oauth:claude-code），若有效或可刷新。
  2. provider 账户已有的凭据存储（在 macOS 上为 Keychain 项 Claude Code-credentials，否则为 ~/.claude/.credentials.json），以只读 方式读取。
  3. 通过受支持的环境变量提供、或在提示时手动粘贴的 setup-token（sk-ant-oat-...）。

若 provider 的 CLI 未安装，Anyy 会打印安装 / 运行 / 重跑指引，并仍允许你粘贴 已有的 setup-token：

1. Install Claude Code:  npm install -g @anthropic-ai/claude-code
2. Run:                  claude setup-token
3. Follow the browser prompts to authorize
4. Re-run:               anyy setup model

该后端登录流程的若干重要性质：

  • Anyy 默认不会改动 provider 账户自身的凭据文件。 Keychain 项与 ~/.claude/.credentials.json 被视为只读来源。刷新令牌时，轮换后的凭据写入 Anyy 自己的 OAuth 密钥存储，而非写回 provider 的文件。
  • 静态 setup-token 绝不会覆盖可刷新的登录凭据。 系统优先使用可刷新的凭据存储， 以便令牌自动续期。
  • 它仅限于这一个后端。 Anthropic 兼容类 provider（自建代理与第三方端点）绝不 读取该登录状态，也绝不接收其身份请求头——它们用各自的 API Key 鉴权。
注意

已登录的 OAuth 凭据是一对实时的 access/refresh 令牌，而非一次性密钥。在 Anyy 中登出只会移除 Anyy 存储的副本（oauth:claude-code）；它不会吊销 provider 账户会话，也不会改动 provider 自己的凭据文件。若要彻底切断访问，还需在 provider 账户中吊销该会话。

密钥存放位置​

所有凭据都以文件形式存放在你的 Anyy home 目录下，与其余本地优先状态放在 一起。Anyy 将其状态保存在一个 home 目录下——普通用户安装时为 ~/.anyy， 以 root 运行时为 /root/.anyy。可通过 --home 标志或环境变量 ANYY_HOME 覆盖（当未能以其他方式解析出 home 时，内置回退值为 /root/.anyy）。配置文件为 <home>/config.yaml（例如 ~/.anyy/config.yaml）。

密钥位于 secrets/ 子树下：

~/.anyy/
├── config.yaml                  # 引用密钥，绝不含原始值
└── secrets/
    ├── <api-key-name>           # profile 本地 API-Key 文件（secret:<name>）
    └── oauth/
        ├── claude-code/         # provider 登录（OAuth）凭据
        │   ├── credential.json  # access 令牌 + refresh 令牌 + 元数据
        │   ├── access_token
        │   ├── refresh_token
        │   ├── metadata.json    # 账户/到期/last_refresh（不含令牌值）
        │   └── pending.json     # 进行中的设备登录状态（临时）
        └── openai-codex/        # 另一个 provider 的登录凭据

运行时强制执行的存储规则：

  • 严格权限。 secrets/ 目录及每个 OAuth 凭据目录以 0700 创建；密钥文件以 0600 写入（仅属主可读写）。
  • 原子写入。 OAuth 凭据文件先写入临时文件再重命名就位，因此写入中途崩溃也不会 留下半写的凭据。
  • 路径受限的引用。 secret: 引用相对于 secrets/ 解析；试图逃逸该目录的引用 （绝对路径、..）会被拒绝。
  • 其余处处用引用而非内联。 配置、工具定义与 provider 定义都通过引用指向密钥； 值仅在需要的那一刻读取。密钥列举 API 只返回引用的名称与元数据——绝不返回值。
注意

secrets/ 子树是 home 目录中最敏感的部分：它保存着原始 API Key 与实时 OAuth 令牌。 请将整个 home 目录限制为你的用户账户访问、将其排除在全员可读的备份之外，并且绝不 提交到版本控制。上述文件权限防范的是其他本地用户，而非把文件复制到别处的备份或同步 工具。

网关与面板访问控制​

出站凭据决定 Anyy 能访问什么；入站访问控制决定谁能访问 Anyy。

网关监听​

Anyy 以常驻**网关（gateway）**运行，供本地客户端连接。其本地传输是 Unix 域套接字（<home>/anyy.sock，例如 ~/.anyy/anyy.sock）。 同一套配置也包含 TCP/WebSocket 监听器；在当前构建中，省略 gateway.tcp 时，TCP 会默认启用，监听 0.0.0.0:8765，模式为 open。在共享机器或局域网上运行前，请 显式检查并加固它。

如果只希望本地访问，请禁用 TCP：

gateway:
  tcp:
    enabled: false

如果确实需要 TCP，请明确绑定地址并选择访问模式：

gateway:
  unix_socket: ~/.anyy/anyy.sock
  tcp:
    enabled: true
    listen: "127.0.0.1:8800"
    mode: token

mode 控制谁可以连接：

模式行为
open不做客户端鉴权——除严格受控的环回场景外应避免使用
token客户端必须出示共享令牌
pairing客户端通过配对交换建立访问；配对令牌本身被视为密钥
allowlist仅显式允许的客户端可连接

面板​

Web 面板（dashboard）是按需启动的边车（sidecar），并非常驻服务。你显式 启动它：

anyy dashboard            # 本地，并在浏览器中打开
anyy dashboard lan        # 同时打印可供局域网内受信设备访问的 URL
anyy dashboard --status   # 查看边车是否在运行
anyy dashboard --stop     # 停止它

访问方式是一次性认领令牌（claim token），换取一个会话 cookie：

  1. 边车签发一个一次性认领令牌，并将其嵌入它打印（或打开）的 URL 中。LAN 模式下 每个打印的 URL 都带有各自的令牌。
  2. 浏览器将该令牌 POST 到面板的认领端点，端点把它换成一个 HttpOnly 会话 cookie （anyy_dashboard_session，SameSite=Lax）。
  3. 后续请求由该 cookie 授权；未鉴权的请求会被弹回认领步骤。面板还会限制它愿意代理的 网关 RPC 方法。
注意

anyy dashboard lan 会把信任边界扩大到所有能访问该打印 URL 的设备。仅与你信任 的设备分享 LAN URL，把 URL 中的认领令牌当作密码对待（它授予一个会话），用完后停止 边车（anyy dashboard --stop）。在未配置令牌或配对以及白名单的情况下， 绝不要把面板或 TCP 网关监听暴露到不受信网络。

轮换与吊销凭据​

轮换或替换 provider API Key：

anyy setup model
# 选择该 provider，然后在密钥提示处选择 [R]eplace

Replace 把新密钥写入同一个密钥引用；旧值被就地覆盖。Clear（[C] 选项）会将该 密钥排入删除队列，显示在 Review Changes 摘要中，仅在你确认后才执行。

登出 provider 的 OAuth 后端： 登出会移除 Anyy 存储的 oauth:claude-code 凭据。如上所述，这不会吊销 provider 账户会话，也不会改动 provider 自己的凭据 文件——若需彻底切断访问，请在 provider 账户中吊销该会话。

刷新自动进行。 对于带 refresh 令牌的登录后端，Anyy 会在运行时刷新即将过期 的 access 令牌（轮换后的令牌写入 Anyy 自己的 OAuth 存储）。通常你无需手动轮换 OAuth 令牌。

轮换网关/面板访问：

  • 重启面板边车（先 --stop 再启动）可使先前打印的认领令牌 URL 失效并签发新的。
  • 在 config.yaml 中更改或禁用 gateway.tcp 设置后重启网关 （anyy gateway restart），即可更改或关闭网络监听。
注意

替换或清除凭据后，请检查配置仍指向的环境变量（env: 引用）或外部文件（file: 引用）中没有残留的旧副本——Anyy 轮换的是它所拥有的值，而非你在别处自行管理的 副本。

鉴权故障排查​

某个 provider 报告“未鉴权 / 需要登录”。 运行 anyy setup model 并确认凭据存在。对于 API Key 类型的 provider，验证 secret: / env: / file: 引用可解析（文件存在，或环境变量已在网关环境中设置）。 随后检查整体健康状况：

anyy doctor

OAuth 登录在浏览器中成功了，但 Anyy 仍要求登录。 重新运行 anyy setup model 并再次选择订阅路径。Anyy 会在 setup-token 命令返回后重新读取 provider 账户的凭据存储；若 provider 的 CLI 未安装，按打印的 安装 / 运行 / 重跑步骤操作，或在提示时粘贴显示出的 setup-token（sk-ant-oat-...）。

令牌过期了。 对于带 refresh 令牌的登录后端，这会在下一次调用时自愈。若某凭据没有 refresh 令牌 （例如静态 setup-token），请重新走登录流程以获取新令牌。

出现计费或权益相关的消息（并非登录错误）。 provider 关于额度或配额用尽的消息属于计费/权益问题，而非鉴权失败。请在 provider 账户中解决；重新鉴权并不会改变它。

面板拒绝你，或不断弹回认领界面。 认领令牌是一次性的，会话 cookie 会过期。请打开正在运行的边车打印的当前 URL （旧 URL 已失效），或重启边车以获取新令牌：

anyy dashboard --stop
anyy dashboard

某个网络客户端无法访问网关。 确认 gateway.tcp.enabled 不是 false、监听地址正确，并且客户端满足所配置的 mode（出示令牌、完成配对，或在白名单中）。配置变更后用 anyy gateway restart 重启。

注意

若你怀疑某凭据已泄露，请将替换视为紧急事项：替换 provider 密钥（并在 provider 账户中 吊销它），重启面板边车以使尚未失效的认领 URL 作废，并复查审计轨迹是否有异常活动。 脱敏与审计保证参见安全与隐私。