别再手写接口文档了！用 Apifox CLI 把整个 API 管理搬进 AI Agent

写在前面

AI 编码时代，大家把 Cursor、Claude Code 用得飞起，但有一个环节始终要"手动挡"：接口文档和 API 数据。

• • 让 Agent 写了个新接口，你得自己把参数、返回值誊到接口文档里；
• • 想让 Agent 依据真实的接口定义写联调代码，它却只能靠猜；
• • 测试用例、Mock 规则、环境变量，全都要在工具界面里点点点。

Apifox CLI 就是为了解决这个断层：它把 Apifox 的主要能力（接口设计、数据模型、Mock、环境变量、测试用例、测试套件……）开放成命令行，让 AI Agent 直接读写你的 Apifox 项目，也方便集成进 CI/CD 流程，与 Apifox 端内功能完全一致。

下面从安装到实战，一次讲清楚。

一、安装

前置条件：Node.js ≥ v16（没装的话先去 nodejs.org 装一个）。

# 国内镜像源（推荐，速度快）npm i -g apifox-cli@latest --registry=https://registry.npmmirror.com/# 或官方 npm 源npm install -g apifox-cli

装完验证一下：

apifox --version   # 输出版本号apifox --help# 查看所有命令

💡 Windows 用户如果提示 apifox: command not found，一般是 npm 全局 bin 目录没加进 PATH，重新全局安装并检查环境变量即可。

二、更新

CLI 自带更新命令，会先检查新版本、询问后再执行 npm 全局更新：

apifox update        # 检查并更新（交互确认）apifox update --yes# 跳过询问，直接更新

也可以用传统方式更新：

npm install apifox-cli@latest -g

三、登录

1. 先拿到 API 访问令牌

打开 Apifox 客户端或网页端：头像 → 账号设置 → API 访问令牌 → 创建并复制。

⚠️ 令牌等同账号密码，不要写进日志、聊天记录或代码仓库。

2. 登录

# 方式一：交互式登录，按提示粘贴令牌apifox auth login# 方式二：命令行直接带令牌（CI/脚本里常用）apifox auth login --with-token <你的令牌># 方式三：私有化部署的 Apifox，指定服务地址apifox auth login --api-base-url <私有化服务地址> --with-token <你的令牌>

登录后验证：

apifox auth whoami# 看当前用户信息apifox project list  # 列出能看到的项目

四、切换账号 / 退出

CLI 支持多账号共存，随时切换当前生效的账号：

apifox auth status        # 查看已登录的所有账号和当前账号apifox auth switch        # 交互式切换当前使用的账号apifox auth logout# 退出当前账号并清除令牌apifox auth logout --all  # 退出所有账号

比如公司账号和个人账号来回切，status + switch 两步就够了，不用反复 login/logout。

五、安装 Skill（给 AI Agent 装上"Apifox 操作手册"）

Skill 是给 AI Agent 看的说明文档，告诉 Agent 怎么正确调用 Apifox CLI。一条命令安装：

apifox skill install

它内部会执行 npx -y skills add https://apifox.com

共包含 8 个技能：

装不满 8 个也没关系，至少要装 apifox-cli 这一个。

六、在 Agent 中使用

1. 推荐先做项目配置

在项目根目录建 .apifox/settings.json，写上项目 ID（在 Apifox 里：项目设置 → 基本设置 → 项目 ID），Agent 后续就不用每次问你要了，记得还要：

{"projectId":123456}

2. 像聊天一样使唤 Agent

配置完成后，直接在 Agent 里下指令即可，例如：

看一下项目里 /user/register 这个接口的定义，包括请求参数和响应结构

给登录接口写一个测试用例，覆盖"密码错误"的场景，写到 Apifox 里

把项目根目录的 openapi.yaml 导入到 Apifox 项目

运行"用户注册全流程"场景用例，跑完把结果总结给我

Agent 会自己组合 CLI 命令完成：读接口定义 → 生成 JSON → 校验 → 写入 → 回读确认。

3. 两道安全机制，放心让 Agent 写

写前校验：复杂资源写入前，Agent 会用 cli-schema 校验 JSON 结构，提前发现缺字段、类型错误：

apifox cli-schema validate test-case-create --file ./test-case.json

AI 分支隔离：Agent 的改动默认进 AI 分支，不直接污染主分支，由你审查后再合并：

# 创建 AI 分支（命名建议：ai/日期-from-来源分支-功能名）apifox branch create --project 123456 --type ai \  --name "ai/20260312-from-main-userRegister" --from main# 审查满意后，按资源 ID 合并到主分支apifox branch merge --project 123456 --type ai \  --from "ai/20260312-from-main-userRegister" --to main --endpoint-ids <ids>

4. 顺手跑个自动化测试

CI 或本地跑场景用例一行搞定，报告自动生成到 ./apifox-reports/：

apifox run -t <场景用例ID> -e <环境ID> -r cli,html

加 --upload-report 还能把报告总览传到云端，直接在 Apifox App 里查看。

七、命令速查

apifox auth login / status / switch / whoami / logout# 账号apifox skill install                                    # 安装 Agent 技能apifox update                                           # 自更新apifox project list / team list                         # 项目与团队apifox endpoint / schema / folder ...                   # 接口、数据模型、目录管理apifox import / export# 30+ 格式导入导出apifox run                                              # 运行场景用例/测试套件apifox branch / merge-request                           # 分支与合并请求apifox cli-schema list / get / validate                 # 资源 JSON 结构校验apifox <command> --help# 任何命令的用法

装好 Node.js，四条命令就能上手：

npm i -g apifox-cliapifox auth login --with-token <你的令牌>apifox skill installapifox project list

官方文档：docs.apifox.com/apifox-cli

如果这篇文章对你有帮助，欢迎点赞、在看、转发三连 👍