快代理 CLI 安装使用

直接调用 HTTP 接口见 Agent Gateway API 接入指南。

一、快速安装

1. 手动安装

在本地终端按以下步骤完成安装。创建凭证需在Agent 设置页面配合完成，登录时在本地终端输入凭证。

安装 CLI

npm install -g @kuaidaili/kdl-agent@0.1.0

若已安装个人包 @zerozhang-giza/kdl-agent，先运行 npm uninstall -g @zerozhang-giza/kdl-agent，再安装公司包。卸载保留 .kdl 配置与 Skill，不要用 --force 覆盖命令。完整步骤见迁移指南。

安装 Skill

npx -y skills@1.5.25 add https://www.kuaidaili.com --skill kdl-agent -g -y

安装后按 AI 助手要求重新加载 Skill。

登录

请用户在Agent 设置创建凭证，并在本地终端执行：

kdl-agent auth login

按提示输入凭证。

验证

kdl-agent account summary --format json

退出码为 0 且返回 success=true 即接入成功。

2. 通过 AI Agent 安装

将以下提示词交给 AI 助手：

帮我安装快代理 CLI：https://www.kuaidaili.com/kdl-agent/docs/install.md

凭证由用户在本地终端输入。安装后可以提问：

查看我的账户状态，列出可用代理订单。

二、日常命令与任务

命令中的 ORDER_ID、MESSAGE_ID、PRODUCT_TYPE、CURSOR 替换为实际值。

1. 查询命令

列表命令的 --limit 有效范围为 1—100。下一页使用返回的 data.next_cursor，保持其原值并加引号：

kdl-agent order list --limit 10 --cursor 'CURSOR' --format json

next_cursor=null 表示结束。CLI 不会自动汇总全部分页，也没有订单 --status 筛选参数；直接 API 可以按状态筛选。不要用“当前页为空”推断整个账户没有订单。

2. 产品报价与待付款订单

报价不会创建订单；product buy 会创建真实待付款订单，需要 product.purchase.create 授权。

1. 查询产品目录和指定产品的当前规格，按 configuration_fields、configuration_rules 构造完整配置。
2. 准备 quote.json，字段为 product_type、spec_version、configuration。详细请求结构见API 产品接口。文件不放 Agent 凭证或订单密钥。
3. 请求报价，检查金额、币种、配置和有效期。不能自行计算一个价格并当作平台报价。
4. 用户已明确要求下单时，将报价返回的 quote_id、product_type、spec_version、configuration 原样放入 purchase.json，生成本次操作独有的 UUID v4 幂等键。
5. 创建成功后返回订单号、pending_payment 状态、金额和 payment_url，用户在官网付款。不能报告成已付款或已交付。

kdl-agent product quote --body-file quote.json --format json
kdl-agent product buy --body-file purchase.json --idempotency-key '本次操作生成的UUID-v4' --format json

--body-file 是推荐方式，可完整保留动态规格。CLI 还提供 --product-type、--spec-version、--pay-mode、--duration-months，下单另有 --quote-id；这些简写不能覆盖所有产品配置。尤其不能为了满足简写参数而编造 spec_version，应原样使用报价结果。

同一次创建发生超时或响应丢失时，保留相同请求体和幂等键再核对或重试，不重新生成键。报价失效后重新报价；修改配置并重新创建属于新的业务操作，不能悄悄当成旧请求重试。

待付款订单不在 order list/show 范围内。刚下单后查询详情返回 404 不能据此判定创建失败，应使用下单响应和官网待付款入口核对。

3. 工单预览与创建

预览只整理问题，不创建工单；真实创建需要 support.ticket.create 授权。

kdl-agent ticket preview --subject '代理连接异常' --body '请根据提供的发生时间和错误情况整理问题说明' --format json

可加 --order-id ORDER_ID 关联订单。预览只接受标题、正文、可选订单号，不接受工单类型、时区或发生时间字段。

创建时优先使用不含凭证、密钥的 ticket.json，包含类型、标题、正文、发生时间段和时区；字段限制见API 工单接口。不要编造问题发生时间，不把预览结果直接当作已创建记录。

kdl-agent ticket create --body-file ticket.json --idempotency-key '本次操作生成的UUID-v4' --format json

也可使用 --type、--subject、--body、--occurred-at-start、--occurred-at-end、--timezone 及可选 --order-id。命令行参数可能保存在 shell 历史中，涉及客户业务描述时优先使用受控文件；文件权限和保留期限由使用者管理，不放进代码仓库。

成功结果包含 ticket_id、pending_reply 和 member_center_url。同一次创建重试复用请求体和幂等键。初版不提交附件。

4. 订单密钥与代理便利命令

下列命令都需要 order.secret.read。权限涵盖按订单获取账户内当前及未来订单的密钥，不是仅对某次命令授权。先阅读密钥边界。

设置多项 IP 可重复使用 --ip。白名单设置不是增量添加；清空和替换必须符合用户明确要求，不作为排障默认动作。获取代理可能消耗订单额度，不能承诺是零副作用的验证。

变更前用 kdl-agent order whitelist get --order ORDER_ID --format json 读取当前列表，返回 ipwhitelist 与 count；变更后再次读取核对。清空不是恢复原配置，原值未知时不要继续写验收。

order secret get 默认表格输出遮蔽 secret_key；需要完整订单密钥时显式使用 JSON。普通查询、代理提取和白名单结果不额外回显密钥。订单密钥不写入 .kdl 或 CLI 缓存，但显式 JSON 输出可被终端、Agent 或外层工具记录，不能把“不落盘”理解为外层系统绝不会保存。

便利命令使用订单 OpenAPI 的规则，不享有 Gateway 创建订单/工单的幂等保证。下游请求结果不确定时先核对业务状态，避免重复提取或误改白名单。Agent 凭证仅发给 Gateway，不发给订单 OpenAPI。

三、从提取到连接代理

订单 SecretId/SecretKey 用于订单 API；连接代理使用订单配置的 Basic 认证或 IP 白名单。两者不能混用。

支持 proxy auth 的 CLI 版本可在内存中获取 Basic 认证（需要 order.secret.read）：

kdl-agent proxy auth --help
kdl-agent proxy auth --order ORDER_ID --format json

返回 type 和 credentials，后者为敏感的 Base64 编码值。默认表格模式隐藏该值。

客户端应把 Basic <credentials> 配置为代理认证。curl 使用 --proxy-header，不要使用发送给目标站的 -H；HTTPS 认证用于 CONNECT。以下本地 Python 示例将认证通过 stdin 交给 curl，不写入文件或命令参数：

import json
import os
import subprocess

order_id = input("订单号：").strip()
proxy = input("已提取的代理 IP:端口：").strip()
if not proxy or any(c not in "0123456789.:[]" for c in proxy):
    raise SystemExit("代理地址格式无效")
auth = json.loads(subprocess.check_output([
    "kdl-agent", "proxy", "auth", "--order", order_id, "--format", "json"
]))
config = 'proxy = "http://' + proxy + '"\n'
config += 'proxy-header = ' + json.dumps("Proxy-Authorization: " + auth["type"] + " " + auth["credentials"]) + '\n'
config += 'url = "https://www.kuaidaili.com/"\n'
subprocess.run(["curl", "--config", "-", "--noproxy", "", "--silent", "--show-error",
                "--fail", "--max-time", "30", "--output", os.devnull,
                "--write-out", "%{http_code}\\n"], input=config, text=True, check=True)

示例需要支持 proxy auth 的 CLI 和本地 curl；目标地址按体验任务调整。不要开启 verbose/trace 或记录认证内容。HTTP 407 先检查代理认证和白名单，重复提取不能补齐认证。

order stats 是已入库的错误/风控摘要；空结果不能证明没有代理鉴权失败。代理侧 407 的上报、订单归属与延迟需结合实际统计记录核对。

四、输出与错误判断

1. 格式

默认 --format table 供人阅读；Agent 使用 --format json，不要解析表格对齐或颜色。可用 --color never 关闭颜色，--help 查看当前版本支持的选项。

普通 Gateway 业务命令成功时输出响应信封。以下是空订单列表的示意，不是实际账户结果：

{
  "success": true,
  "data": {"items": [], "next_cursor": null},
  "request_id": "req_example",
  "error": null
}

以下命令是直接结果对象，不套同一信封：

2. stdout、stderr 与退出码

结果进入 stdout，错误和风险提示进入 stderr。即使选择 JSON，错误诊断当前仍是文本；不能假定 stderr 总能解析成 JSON，也不能看到 Secret 命令的风险提示就认定请求失败。

自动化先检查非零退出码，再处理 stdout。错误中有 request_id 时保留它用于排查；网络请求未到达服务端时可能没有此字段。

新版 CLI 遇到 429 时会在 stderr 提示服务端 Retry-After 等待秒数；按提示退避，不立即循环重试。CLI 不自动重放业务请求。

五、授权凭证与订单密钥

1. 三类凭据

Agent 凭证由会员中心管理。创建时核对有效期；默认有效期为 90 天，每账户最多 10 张 active 凭证，不支持永久凭证。凭证丢失且无法恢复时重新创建合适的凭证，并按需撤销旧凭证。

2. 三项敏感授权

三项默认关闭，在Agent 设置按需开启。授权有效且用户已明确要求执行的业务动作，不再由 CLI 每次增加确认步骤；任务目标或关键参数不明确时仍需先澄清。基础查询仍要求有效凭证并受账户、订单归属和服务规则约束。

3. 本地保存

发行版使用操作系统用户家目录：

~/.kdl/
  config.toml        # Gateway 等普通配置
  credentials.toml   # 按 Gateway 绑定的明文 Agent 凭证

Windows 对应 %USERPROFILE%\.kdl\。macOS/Linux 目录权限为 0700、凭证文件为 0600；Windows 使用对应用户访问权限。默认不从当前项目目录发现或写入凭证，切换工作目录不切换账户。

凭证明文保存，同一系统用户运行的程序可读取。不要共享 .kdl 或让 Agent 读取凭证文件。

自动化场景可以通过 KDL_AGENT_GATEWAY_URL、KDL_AGENT_TOKEN 注入地址和凭证，当前运行的注入覆盖本地配置且不自动落盘。由运行环境管理秘密值，不通过聊天生成含真实凭证的脚本。切换 Gateway 时应使用该地址对应的凭证，不自动复用旧地址凭证。

普通客户无需设置自定义配置文件。需要时，普通配置路径优先级为 --config > KDL_AGENT_CONFIG > 家目录 .kdl/config.toml；显式相对路径相对当前工作目录，凭证仍固定在家目录。auth status --format json 区分 unconfigured、valid、invalid、unreachable 与 error，只有 valid 表示远端验证有效；验证成功时展示 Gateway 返回的三项 grant 状态，旧服务未返回的项表示未知，不等于未授权。

4. 退出、撤销与密钥重置

订单密钥读取授权意味着密钥可能进入你选择的 Agent、模型或相关服务。怀疑泄露时，仅退出 CLI 或关闭 grant 不够；还需在订单 API 设置中完成重置，并同步更新其他客户端，核对旧密钥实际失效时间。

可在安全记录查看凭证及授权变更，在调用监控查看 Gateway 调用。便利命令直接调用的订单 OpenAPI 不应被误认为全部记录在 Gateway 监控中。

六、版本与升级回退

查看当前版本：

kdl-agent --version

升级或回退时，将下方版本号替换为版本记录中的目标版本，同步安装 CLI 和 Skill（示例目标为 Codex）：

npx --yes @kuaidaili/kdl-agent@0.1.0 install --yes --agent codex --no-login

升级保留登录配置；Skill 安装失败时重试同一命令。完成后核对版本、刷新 Agent 会话，再执行一次账户查询。发布新版不会静默替换本机安装。

后续支持 update check 的版本会由 Skill 在任务开始时检查新版，提示并经你确认后同步升级。旧版需要先按上述流程升级一次。

卸载：

kdl-agent auth logout
npm uninstall -g @kuaidaili/kdl-agent

卸载 npm 包不删除 Skill；按 AI 助手的管理方式移除。

七、常见问题与排障

反馈问题时提供：发生时间与时区、操作系统和架构、CLI 版本、去除敏感参数的命令、错误码及 request_id。不要附带 .kdl、旧配置文件、完整环境变量、订单 Secret 输出、未经脱敏的业务正文或终端录像。