使用 Apifox CLI 搭配 AI Agent

Apifox CLI 旨在将 Apifox 的 API 全生命周期能力引入 AI Agent 工作流。通过 Apifox CLI 和 Apifox AI Agent Skills，AI Agent 可以使用命令行工作流查询项目资源、运行自动化 API 测试、在写入前校验数据，以及管理 API 或测试资产。

Apifox CLI 适合 AI Agent 使用，因为它提供稳定、可验证的工程操作，而不是要求 Agent 逐个调用大量小工具。

产品概览请参见 Apifox CLI。

AI Agent 可以用 Apifox CLI 做什么

安装并完成认证后，AI Agent 可以使用 Apifox CLI 协助完成以下任务：

查看和管理 API 资源，包括接口、数据模型、目录、参数、响应定义、响应示例和标签。

基于 API 定义创建和更新接口测试用例。

管理自动化测试场景和测试套件。

在命令行、本地脚本或 CI/CD 流水线中运行自动化测试场景和测试套件。

生成 CLI、HTML、JSON、JUnit 等格式的测试报告。

管理环境、变量和运行时配置。

导入和导出 30+ 种格式的 API 数据，例如 OpenAPI、Postman、HAR、JMeter、WSDL、Markdown 和 Apifox 原生格式。

管理 API 文档站点和共享文档。

管理测试数据集，用于数据驱动测试。

使用分支能力，包括用于安全隔离 Agent 生成变更的 AI 分支。

为什么使用 Apifox CLI，而不是只使用 MCP 工具？

MCP 工具通常暴露许多原子化 API 操作。Apifox CLI 则提供更高层级的命令，更贴近常见研发工作流。

相比只使用 MCP 工具，Apifox CLI 可以帮助 AI Agent：

执行更高粒度的操作，例如读取 → 校验 → 写入 → 验证。

通过 cli-schema validate 进行运行时 Schema 校验。

返回带有 agentHints 的结构化命令输出，引导下一步操作。

在写入前进行数据校验，提前发现创建或更新资源时可能出现的问题。

减少重复工具调用，降低 token 消耗。

前置要求

在通过 AI Agent 使用 Apifox CLI 前，请确保：

已安装 Node.js 和 npm/npx。

已拥有 Apifox 账号。

当前账号有权限访问需要让 Agent 操作的 Apifox 项目。

已安装 Apifox CLI。

Apifox CLI 已通过 Apifox API 访问令牌完成认证。

已为你的 Agent 安装 Apifox AI Agent Skills。

安装详情请参见 Apifox CLI 安装引导。

安装 Apifox CLI

安装或升级 Apifox CLI：

如果镜像源较慢或不可用，可以改用 npm 官方源：

验证安装结果：

你也可以直接让 AI Agent 阅读并执行安装引导：

Read https://apifox.com/apifox-cli-installation-guide.md and follow instructions.

获取 API 访问令牌

在 Apifox 客户端或网页端中获取访问令牌：

点击用户头像。

打开 账号设置。

进入 API 访问令牌。

创建并复制 token。

不要在日志、聊天消息、仓库文件或截图中打印 token。

登录 Apifox CLI

使用 token 登录：

检查当前登录身份：

列出可访问的项目：

如果已经知道项目 ID，可以通过资源查询命令验证访问权限：

记录长期使用的工作项目

对于 Agent 工作流，建议将常用项目 ID 保存到 .apifox/settings.json。

项目 ID 获取路径：

项目 → 项目设置 → 基本设置 → 项目 ID

然后创建 .apifox/settings.json：

{
  "projectId": 123456
}

当用户请求没有明确指定项目时，AI Agent 可以使用此文件中保存的 projectId。

同时建议确保 .apifox/.gitignore 包含：

*.private.*

安装 Apifox AI Agent Skills

安装 Apifox AI Agent Skills，让 Agent 知道如何正确使用 Apifox CLI：

该命令会启动交互流程，你可以选择要安装的 Skills、目标 AI Agent 和安装范围。

也可以通过 GitHub 仓库安装：

如果当前环境无法访问官方安装源，请按照所用 AI Agent 的规则手动安装 Apifox AI Agent Skills。使用 WebFetch 获取：

https://apifox.com/.well-known/agent-skills/index.json

然后根据其中的 url 字段下载并安装所需的 SKILL.md 文件。

推荐安装全部 8 个 Skills。至少应安装 apifox-cli。

Apifox AI Agent Skills 如何提供帮助

Apifox CLI + SKILL.md 面向 AI Agent 集成而设计。Skills 系统通过以下方式帮助 Agent 正确使用 CLI：

任务感知调用：Agent 可以根据任务匹配相关 Skills，无需反复指定 CLI 使用方式。

判断规则：指导 Agent 何时需要校验、何时需要回读、何时不能猜测 ID。

工作流指导：通过命令输出中的 agentHints 推荐下一步操作。

AI 分支安全机制：可在隔离的 AI 分支中进行变更，避免直接污染项目数据。

当前 Apifox Skills 发现索引包含：

apifox-cli

apifox-test-case

apifox-test-automation

apifox-test-scenario

apifox-branch

apifox-cli-checkup

apifox-import-export

apifox-workflow-api-lifecycle

使用 AI 分支保障 Agent 生成变更的安全性

当 AI Agent 需要修改 API 或测试资产时，应尽量使用 AI 分支。

AI 分支可以帮助隔离 Agent 生成的变更：

将 Agent 修改与主分支隔离。

提醒用户这些变更尚未合并。

合并前需要用户确认。

默认情况下，为了安全，项目写入权限可能受到限制。如需直接编辑主分支，请在项目 AI 功能设置中开启外部 AI 编辑权限。

写入前校验数据

当 Agent 创建或更新结构化资源时，应在写入前使用 cli-schema validate。

例如：

该校验可以帮助发现以下问题：

缺少必填字段。

类型不匹配。

结构错误。

枚举值无效。

字段名无效。

Agent 工作流示例

一个典型的 Apifox CLI + AI Agent 工作流如下：

用户要求 Agent 检查、测试或更新某个 Apifox 项目。

Agent 检查 .apifox/settings.json，或向用户询问目标项目 ID。

Agent 使用 apifox whoami 验证 CLI 登录状态。

Agent 通过 CLI 命令读取项目资源。

如果需要写入数据，Agent 先准备本地 JSON 文件。

Agent 使用 cli-schema validate 校验文件。

Agent 通过 Apifox CLI 应用变更。

Agent 回读更新后的资源或测试结果，验证变更是否生效。

如果变更发生在 AI 分支中，用户在合并前进行审查和确认。

通过 AI Agent 运行测试

Agent 可以使用 Apifox CLI 运行自动化 API 测试。

运行测试场景：

运行测试套件：

使用 apifox run --help 查看当前已安装 CLI 版本支持的最新命令选项。

最佳实践

使用 Apifox CLI 搭配 AI Agent 时，建议：

安全存储访问令牌。不要将 token 放入提示词、日志、仓库文件或截图中。

当 Agent 经常操作同一个项目时，将常用项目 ID 保存到 .apifox/settings.json。

使用 apifox whoami 验证当前登录身份。

当命令参数不明确时，使用 apifox <command> --help 查看说明。

在创建或更新结构化资源前使用 cli-schema validate。

对 Agent 生成的变更优先使用 AI 分支。

变更后回读资源或测试结果，验证操作结果。

使用 CI/CD 命令构建可重复的自动化测试工作流。

故障排查

问题	解决方案
`apifox: command not found`	重新全局安装 Apifox CLI，并确认 npm global bin 目录已加入 `PATH`。
未登录	重新执行 `apifox login --with-token <TOKEN>`。
项目不存在或无权限	检查项目 ID，并确认 token 对应账号有权限访问该项目。
不确定命令参数	执行 `apifox <command> --help` 查看最新用法。
Invalid characters in header content	检查环境变量初始值、认证请求头值，以及换行、多余空格等隐藏字符。

使用 Apifox CLI 搭配 AI Agent

AI Agent 可以用 Apifox CLI 做什么#

为什么使用 Apifox CLI，而不是只使用 MCP 工具？#

前置要求#

安装 Apifox CLI#

获取 API 访问令牌#

登录 Apifox CLI#

记录长期使用的工作项目#

安装 Apifox AI Agent Skills#

Apifox AI Agent Skills 如何提供帮助#

使用 AI 分支保障 Agent 生成变更的安全性#

写入前校验数据#

Agent 工作流示例#

通过 AI Agent 运行测试#

最佳实践#

故障排查#

AI Agent 可以用 Apifox CLI 做什么

为什么使用 Apifox CLI，而不是只使用 MCP 工具？

前置要求

安装 Apifox CLI

获取 API 访问令牌

登录 Apifox CLI

记录长期使用的工作项目

安装 Apifox AI Agent Skills

Apifox AI Agent Skills 如何提供帮助

使用 AI 分支保障 Agent 生成变更的安全性

写入前校验数据

Agent 工作流示例

通过 AI Agent 运行测试

最佳实践

故障排查