如何进行 Apifox CLI 的身份验证：登录、Token 与 CI Secrets

当你第一次运行 apifox run 并因 “No access token found” 而停止时，你遇到了命令行工作流中那个没人警告过你的环节。参数（flags）、测试场景 ID 和报告器都很容易从标签页中复制。但身份验证是一个关键步骤，复制的命令可能会在你的机器上失效，将密钥泄露到日志中，或者在你的笔记本电脑上默默正常工作，却在 CI 中因为错误消息未解释的原因而失败。

本指南将专门解答这一问题。Apifox CLI 是一个 npm 包（apifox-cli），可以直接在终端运行你在 Apifox 应用中构建的 API 测试场景。由于这些测试场景保存在你的账户中，CLI 必须证明其已被授权获取并运行它们，而这是通过访问令牌来实现的。一旦正确处理了 Token，此后的每次运行都只需简单的一行命令。如果处理不当，你将在三种不同的环境中反复排查相同的 auth 错误。

我们将涵盖所有内容：生成访问令牌、使用 apifox login 登录、使用 apifox whoami 检查当前的登录身份、Token 的存储位置、apifox run 如何决定使用哪个 Token，以及大多数团队都会犯错的部分——在 CI 中将该 Token 作为 secret 处理，而不是直接粘贴到流水线文件中。安装机制在另一篇单独的指南中介绍；本篇仅讨论 auth。如果你还没有安装 CLI，请先阅读 Apifox CLI 安装指南，然后再返回此处。

为什么 CLI 需要 Token

CLI 本身不携带测试。它会访问你的 Apifox 项目，通过 ID 找到测试场景，并以与桌面版相同的方式运行它。这种设计就是它需要进行身份验证的原因：测试场景、环境值、断言都保存在你账户的服务端，因此在服务端交付这些内容之前，runner 必须表明自己的身份。

访问令牌就是它识别身份的方式。Token 与你的 Apifox 账户绑定，因此使用你的 Token 进行身份验证的运行可以执行你所能执行的操作：读取项目、获取测试场景，并在你定义的环境中执行它们。这也是你需要保护该 Token 凭据的原因。任何持有它的人都可以以你的身份运行测试场景，并针对这些测试场景所指向的任何环境进行操作。请像对待其他任何服务的个人访问令牌（personal access token）一样对待它。

这与你的测试所执行的 auth 是不同类型的身份验证。你的测试场景可能会将它们自己的 Bearer Token 或 API Key 发送到被测接口，这是一个独立的问题，在 API 身份验证方法中会单独介绍。CLI 的访问令牌用于向 Apifox 验证 runner 的身份。而你请求中的凭据则用于向你的 API 验证请求的身份。请分清这两者，因为它们存在于不同的地方，且有不同的轮换周期。

步骤 1：生成访问令牌

你需要在 Apifox 中创建 Token，而不是通过 CLI 创建。它会在两个地方出现，具体使用哪一个取决于你当前的操作。

如果你需要一个绑定到账户且要在多个测试场景中复用的 Token，请打开 Apifox 客户端或 Web 版控制台，点击你的头像，然后在账户设置中找到“API 访问令牌”区域。

生成一个 Token，立即复制并妥善保存到密码管理器等安全的地方。离开该页面后，你通常无法再次查看完整的字符串，这对于凭据来说很正常，也是为什么要在它显示时立即复制的原因。

对于要集成到 CI 中且与特定测试场景绑定的 Token，有一种更快捷的方法。打开该测试场景，切换到其 CI/CD 标签页，选择命令行选项，然后点击生成访问令牌。Apifox 会为你构建完整的 apifox run 命令，其中已自动填充 Token、场景 ID 和环境 ID。这个生成的命令是标准的起点，复制它意味着你无需手动输入任何 ID。完整的 Apifox CLI 指南详细介绍了该 CI/CD 标签页。

无论哪种方式，最终生成的都是相同的东西：一个 Token 字符串。接下来如何使用它，取决于你选择哪种 auth 方式。

步骤 2：选择你的 auth 方式

CLI 支持两种提供 Token 的方式，它们适用于不同的场景。

第一种是保存登录状态。你只需运行一次 apifox login，CLI 就会将 Token 保存到你的机器上，此后的每次 apifox run 都会自动读取它。命令行中无需再出现 Token。这就是你在日常使用的开发机上所需要的。

第二种是单次命令传参。你直接在调用 apifox run 时传入 --access-token，这通常来自环境变量。这样本地不会保存任何内容，每次运行都会重新提供 Token，且不会在磁盘上留下任何痕迹。这就是你在 CI 中所需要的，因为 CI 的 runner 是临时的，且 Token 来自机密变量。

你可能会同时使用这两种方式：本地使用保存登录状态，流水线中使用单次命令传参方式。接下来的两节将分别介绍这两种方式。

在你自己的机器上，登录一次即可，无需再关心 Token。交互式表单会提示你输入 Token，因此该字符串永远不会出现在你的 shell 历史记录中：

apifox login

CLI 会要求输入你的访问令牌，粘贴后按回车即可。在保存任何内容之前，CLI 会在后台向 Apifox 验证该 Token；无效或过期的 Token 会被当场拒绝，而不是等到你第一次运行测试时才报错。验证成功后，它会确认登录的账户，并告知你凭据的存储位置。

如果你更愿意直接传递 Token（例如在安装脚本中），可以使用 --with-token 参数：

apifox login --with-token YOUR_ACCESS_TOKEN

使用这种方式时需要注意一点：命令行中的 Token 会留存在您的 shell 历史记录中，并且在命令运行时可以从进程列表中被读取。对于手动操作，建议优先使用交互式的 apifox login，而将 --with-token 留给非交互式设置（即从您控制的变量中读取值）。千万不要将真实的 Token 写入您提交的脚本中。

Token 会保存在哪里？CLI 会将其写入您主目录下 .apifox 目录中的配置文件中。这是您自己机器上的本地凭据存储，这也正是其目的所在：Token 存在磁盘上，只有您的用户账户可以读取它，CLI 会在以后的每次运行中自动读取它，而无需您重新输入。如果您使用的是共享机器或临时机器，请跳过保存登录信息，改为使用单次命令的 Token，这样在您离开后就不会留下任何残留。

步骤 4：使用 apifox whoami 进行验证

登录后，在开始后续操作之前，先确认登录是否成功：

apifox whoami

这会打印出 CLI 当前已通过身份验证的账号。这是无需运行真实测试场景即可快速回答“我是否已登录？以谁的身份登录？”的最快方法。每当运行由于 auth 错误而失败，并且您不确定问题出在 Token 还是下游的其他地方时，都可以使用此命令；如果 whoami 显示了您的账号，说明保存的登录状态没有问题，您可以去排查其他地方。

如果您想检查特定的 Token 而不是已保存的 Token，apifox whoami 也支持接收 --access-token 参数。这对于在流水线中信任 CI Token 之前确认其有效性非常有用：在安全的终端中将 Token 粘贴到一次性的 apifox whoami --access-token YOUR_ACCESS_TOKEN 命令中，查看其解析为哪个账号，然后将其移入您的机密存储中。

当您在共享机器上操作完毕，或者想要切换到其他账号时，请清除保存的凭据：

 apifox logout

这将从配置文件中删除已保存的 Token。下一次执行 apifox run 时，将需要重新登录或提供 --access-token 标志，这正是您在归还机器后所期望的行为。

步骤 5：apifox run 如何选择 Token

一旦您了解了 runner 检查的顺序，“No access token found”（未找到访问令牌）的错误就不再神秘了。当您调用 apifox run 时，CLI 会按照以下顺序查找 Token：

命令行中传递的 --access-token 标志（如果存在）。
之前通过 apifox login 存储在磁盘上的 Token。

如果两者都未找到，它将停止运行并提示您先运行 login 或传递 --access-token。这种优先级顺序非常实用：命令行标志的优先级总是高于保存的登录状态，因此您日常可以保持登录自己的账号，而在进行单次运行时，无需注销即可通过另一个 Token 来覆盖它。

在实际操作中，这意味着您的本地运行命令可以像只包含 ID 一样简短：

apifox run -t 605067 -e 1629989 -n 1 -r cli

该命令行中没有 Token，因为已保存的登录信息会提供它。-t 通过 ID 指定测试场景，-e 选择环境，-n 1 运行一次，而 -r cli 则打印易读的报告。相比之下，在 CI 形式中，你需要显式传递 Token，因为没有保存任何内容：

apifox run --access-token "$APIFOX_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

相同的命令，相同的测试场景，不同的 auth 来源。这就是本地与 CI auth 的全部区别，本指南的其余部分将介绍如何正确配置 CI。有关这些运行背后完整的参数参考，Apifox CLI 完整指南涵盖了每个选项。

步骤 6：在 CI 中将 Token 作为机密处理

这是很多团队容易踩坑的地方。解决方法只有一个规则：Token 存在于你的 CI 系统的机密存储中，并通过环境变量传递给命令。它绝不能出现在已提交的文件、检入仓库的流水线定义或构建日志中。

不要在 CI 内部进行登录，也不要将 Token 写入 runner 创建的文件中。请使用单条命令的 --access-token 形式，并从已遮蔽的机密（masked secret）中获取值。以下每个示例都遵循相同的结构，在平台中命名一次机密，并在运行步骤中引用为 $APIFOX_ACCESS_TOKEN。

GitHub Actions

将 Token 存储在仓库的 Settings 中的 Secrets and variables 下，然后通过 env 将其暴露给该步骤：

- name: Run API test scenario
  run: |
    apifox run \
      --access-token "$APIFOX_ACCESS_TOKEN" \
      -t 605067 \
      -e 1629989 \
      -r junit,cli
  env:
    APIFOX_ACCESS_TOKEN: ${{ secrets.APIFOX_ACCESS_TOKEN }}

GitHub 会自动在日志中遮蔽（mask）该机密，通过 env 传递可以避免它在命令行中显式暴露。这里最常见失败原因是名称不匹配：env 键、${{ secrets.X }} 引用以及在 Settings 中创建的机密必须使用相同的名称。包含报告产物在内的完整工作流请参阅 GitHub Actions 中的 Apifox CLI 指南。

GitLab CI

将 APIFOX_ACCESS_TOKEN 存储为 Settings 下的 masked（已遮蔽）、protected（受保护）的 CI/CD 变量，切勿写入 .gitlab-ci.yml 文件中。然后直接引用它，因为 GitLab 会将项目变量注入到作业环境中：

api-tests:
  stage: test
  image: node:20
  script:
    - npm install -g apifox-cli
    - apifox run --access-token "$APIFOX_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

将变量标记为“masked”会使 GitLab 在作业日志中将其隐藏（遮蔽）；将其标记为“protected”可以使其远离未受保护的分支，从而防止 fork 或功能分支泄露该变量。

Jenkins

将 Token 存储为 Jenkins 凭据，然后在 environment 块中对其进行绑定，以便将其作为变量使用，而不会被打印出来：

pipeline { agent any environment { APIFOXACCESSTOKEN = credentials('apifox-access-token') } stages { stage('API tests') { steps { sh 'apifox run --access-token $APIFOXACCESSTOKEN -t 605067 -e 1629989 -r junit,cli' } } } }

Jenkins 会在控制台输出中遮蔽以这种方式绑定的凭证。如果您围绕此步骤构建完整的流水线，CI/CD 流水线中的 Apifox CLI 即可处理其周边的执行结构。

所有 runner 上的模式都是完全相同的：在平台中遮蔽机密信息、在命令中使用环境变量，以及通过 --access-token 标志读取该变量。这与您在流水线中处理任何凭证的原则相同。如果您需要管理多个 API 密钥，非常建议阅读 API 密钥管理最佳实践。

轮换和撤销 Token

Token 并非永久有效。请定期轮换它们，并在可能发生泄漏时立即予以撤销。

轮换时，在 Apifox 中生成一个全新的 Token，在每个使用它的 CI 系统中更新该机密信息，然后运行流水线以确认新 Token 工作正常。接着，在您创建旧 Token 的相同位置将其撤销。在本地，依次运行 apifox logout 和 apifox login（使用新 Token）。顺序非常重要：必须先更新 CI，然后再撤销旧 Token，否则在这两个步骤之间可能会导致构建失败。

如果 Token 出现在不该出现的地方（例如日志、截图、提交记录或共享终端），请立即撤销。撤销会同时使该 Token 在所有地方失效，因此任何仍在使用旧值的流水线都会立即报错失败，而这正是您预期的警示信号。构建失败是可以挽回的，但公开日志中暴露的有效凭证却无法撤回。为了养成更好的习惯，您可以参考 API 密钥轮换最佳实践来了解推荐的轮换频次。

一个容易忽视的陷阱：在 Apifox 中重新生成 Token 会使前一个 Token 失效。如果您重新生成了 Token 但忘记更新 CI 中的机密信息，那么即使 YAML 文件没有任何变化，该流水线也会因 auth 错误而开始报错。当原本可以正常通过的构建突然无法通过身份验证，且您并没有修改工作流文件时，首先需要检查的就是 Token 是否被重新生成了。

当身份验证失败时

Auth 错误通常由以下几种原因引起。以下是如何区分它们的方法。

“No access token found.”（未找到访问令牌）。CLI 既没有找到 --access-token 标志，也没有找到已保存的登录信息。在本地，请运行 apifox login。在 CI 中，请确认已填入机密信息，且 --access-token 标志正在读取它；如果环境变量为空，也会输出同样的信息。

“Invalid access token”（无效的访问令牌）或运行中途出现 auth 错误。这意味着 Token 错误、已过期或已被撤销。运行 apifox whoami 来检查保存的 Token，或运行 apifox whoami --access-token YOUR_TOKEN 来检查特定的 Token。如果两者的查询结果都不是您的账户，请生成一个全新的 Token 并重新登录。

本地运行正常，但在 CI 中失败。这是配置不一致的经典问题。你的本地机器上保存了登录状态，因此本地运行成功；而 CI runner 没有存储任何内容，完全依赖于 Secret。请确认平台设置与命令中的 Secret 名称完全一致，并确保保存的值没有尾随空格或换行符（这在复制粘贴时很容易引入）。

特定测试场景显示“Access denied”（拒绝访问）。Token 是有效的，但其背后的账号无法访问该项目。请检查项目 ID 和测试场景 ID，并确认 Token 对应的账号拥有该项目的访问权限。这是一个授权问题，而不是认证问题；CLI 已经证明了自己的身份，服务端只是不允许该账号运行该测试场景。

Token 成功传递到了命令中，但构建过程仍然泄露了它。如果你在日志中看到了明文 Token，说明你在某个地方输出了它，这通常发生在打印完整命令或环境的调试行中。对其进行遮蔽（Mask）：只打印 Token 的长度以确认其已被填充，千万不要打印它的值。大多数 CI 平台会自动脱敏已知的 Secret，但手动对整个命令执行 echo 可能会绕过这一保护机制。

auth 如何融入整体工作流

认证是一道微小且一次性的门槛，它让下游的一切工作成为可能。一旦 CLI 能够证明自己的身份，运行 Apifox 测试场景就变成了一个简单的命令——无论是在你本地的“编辑-测试”循环中，还是在每次推送时的 CI 中，甚至是在为你运行测试的 AI 编码 Agent 中。如果你在使用 Agent，最后一种模式非常值得关注：《如何使用 AI Agent 进行 API 测试》展示了已登录的 CLI 如何让 Agent 运行你的测试场景并读取结果，而 Apifox MCP 服务端则可以直接将你的接口定义与这些 Agent 连接起来。

它的心智模型非常简单。在你的机器上使用 apifox login 登录一次，使用 apifox whoami 进行验证，然后让存储的 Token 承载后续的每一次运行。在 CI 中，跳过登录步骤，将 Token 保存在遮蔽的 Secret 中，并在每个命令中通过 --access-token 传递。定期轮换 Token，发现异常时立即撤销，并在撤销前更新 CI。这就是整个 auth 的全部内容，搞定这些后，CLI 就会退居幕后，正如一个优秀的测试 runner 该有的样子。

你可以继续在 Apifox 中以可视化方式编写测试场景，而 CLI 则会在无人值守的任何地方运行它们。下载 Apifox 来创建你的第一个测试场景，然后让 runner 指向它。关于 runner 在完成认证后能做的所有事情，完整的 Apifox CLI 指南是值得随时查阅的参考文档。