阿里雲 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 外掛程式專用配置。