阿里云 CLI 的帮助信息和错误提示面向人工阅读，AI Agent 解析成本高、试错次数多。开启 AI 模式后，CLI 在请求的 User-Agent 中标识调用方为 AI Agent。CLI 本地的输出也改为便于程序解析的形式。

功能介绍

AI 模式带来的变化：

云产品服务端据此区分 Agent 调用和人工操作，用于问题排查和调用统计。
Agent 可以直接解析 CLI 的输出，减少重试次数。

说明

AI 模式不改变 API 调用的权限和请求参数。
AI 模式不保证向前兼容，自动化流程如需使用 AI 模式，请勿依赖固定输出结构。

AI模式的行为变化

AI 模式的能力需要阿里云 CLI 3.5.0 及以上版本。开启后，CLI 的本地输出变化包括但不限于：

帮助信息以更紧凑的形式输出。
错误信息以结构化形式输出，包含失败原因和下一步操作。
参数取值在本地校验。
输出不含颜色控制符。

内容以摘要形式呈现时，输出会给出获取完整内容的方式。

管理 AI 模式

AI 模式通过 aliyun configure ai-mode 命令族管理。

查看当前配置

执行以下命令查看 AI 模式的当前配置：

aliyun configure ai-mode show

输出示例：

{
  "enabled": true,
  "user_agent": "",
  "effective_user_agent": "AlibabaCloud-Agent-Skills",
  "request_user_agent_suffix": "AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills",
  "config_file": "/home/user/.aliyun/ai-mode.json"
}

字段说明：

字段	说明
`enabled`	AI 模式是否启用。
`user_agent`	自定义的 User-Agent 技能标识段。为空表示使用默认值。
`effective_user_agent`	实际生效的技能标识段。自定义值或默认值 `AlibabaCloud-Agent-Skills`。
`request_user_agent_suffix`	追加到请求 User-Agent 中的完整后缀。
`config_file`	配置文件路径。

启用和禁用

通过命令

执行以下命令启用或禁用 AI 模式：

# 启用 AI 模式
aliyun configure ai-mode enable

# 禁用 AI 模式
aliyun configure ai-mode disable

通过环境变量

AI 模式的状态通过以下环境变量传递。可以手动设置这些变量控制 AI 模式：

环境变量	说明
`ALIBABA_CLOUD_CLI_AI_MODE`	值为 `1` 或 `true` 表示启用 AI 模式，值为 `0` 或 `false` 表示关闭。
`ALIBABA_CLOUD_CLI_AI_USER_AGENT`	AI 模式下追加的完整 User-Agent 后缀。例如 `AlibabaCloud-AIMode/enabled AlibabaCloud-Agent-Skills`。

说明

在 Agent 运行环境中，执行 export ALIBABA_CLOUD_CLI_AI_MODE=1 可在当前会话中开启 AI 模式。会话内的所有命令都生效，不必逐条追加 --cli-ai-mode 标志。如需持久化配置，请使用 configure ai-mode 命令。

自定义 User-Agent 技能标识段

默认的技能标识段是 AlibabaCloud-Agent-Skills。如果需要区分不同的 AI Agent，可以自定义该值：

# 设置自定义技能标识段
aliyun configure ai-mode set-user-agent --user-agent "MyAgent/1.0"

# 恢复默认值
aliyun configure ai-mode reset-user-agent

自定义后，请求的 User-Agent 后缀变为：

AlibabaCloud-AIMode/enabled MyAgent/1.0

单命令覆盖

在调用 OpenAPI 时，可以使用命令行标志覆盖全局 AI 模式设置，仅对当前命令生效：

标志	效果
`--cli-ai-mode`	仅本次命令启用 AI 模式（即使全局未开启）。
`--no-cli-ai-mode`	仅本次命令关闭 AI 模式（即使全局已开启）。

如果同时使用两个标志，--no-cli-ai-mode 优先级更高。

示例：

# 全局未开启 AI 模式，但本次调用追加 AI 标识
aliyun ecs DescribeInstances --cli-ai-mode

# 全局已开启 AI 模式，但本次调用不追加
aliyun ecs DescribeInstances --no-cli-ai-mode

配置文件

如需手动查看或备份AI 模式的配置文件，可在以下路径找到：

操作系统	存储路径
Linux / macOS	`~/.aliyun/ai-mode.json`
Windows	`C:\Users\<USER_NAME>\.aliyun\ai-mode.json`

文件格式示例：

{
  "enabled": true,
  "user_agent": "MyAgent/1.0"
}

字段说明：

字段	类型	说明
`enabled`	boolean	是否启用 AI 模式。默认为 `false`。
`user_agent`	string	自定义 User-Agent 技能标识段。为空时使用默认值 `AlibabaCloud-Agent-Skills`。

说明

如果配置文件不存在，AI 模式默认为禁用状态。请通过 aliyun configure ai-mode 命令管理配置，不要手动编辑配置文件。

优先级

AI 模式的生效优先级从高到低如下：

命令行标志（--cli-ai-mode / --no-cli-ai-mode）
环境变量（ALIBABA_CLOUD_CLI_AI_MODE）
配置文件（ai-mode.json）

高优先级的设置生效时，低优先级的设置被忽略。如果同时指定了 --cli-ai-mode 和 --no-cli-ai-mode，以 --no-cli-ai-mode 为准。

生效范围

AI 模式在以下场景生效：

OpenAPI 调用：通过命令发起的 RPC 和 RESTful 请求，User-Agent 中会追加 AI 标识段。
插件命令：CLI 通过环境变量（ALIBABA_CLOUD_CLI_AI_MODE 和 ALIBABA_CLOUD_CLI_AI_USER_AGENT）向插件子进程传递 AI 模式状态。插件可据此在自身请求中追加对应标识。

附录：子命令参考

以下是 aliyun configure ai-mode 下的所有子命令：

子命令	说明
`show`	查看当前 AI 模式配置。
`enable`	全局启用 AI 模式。
`disable`	全局禁用 AI 模式。
`set-user-agent --user-agent <value>`	设置自定义 User-Agent 技能标识段。
`reset-user-agent`	将技能标识段恢复为默认值 `AlibabaCloud-Agent-Skills`。
`set-ossutil --ossutil <json>`	设置 ossutil 插件专用配置（JSON 格式字符串）。
`reset-ossutil`	清除 ossutil 插件专用配置。