Agent Runtime agr CLI 安装与配置

agr 是 Agent Runtime 的命令行工具。本文说明如何安装 agr CLI、写入本地凭据，并验证配置是否可用。
前提条件
已获取腾讯云 SecretId 和 SecretKey。
安装环境可以使用 go install，或者可以从源码执行 make build。
如果运行环境的 Home 目录不可写，请提前准备一个可写配置路径，并在命令中通过 --config 显式传入。
步骤 1：安装 agr CLI
安装后建议立即验证版本，确认命令已加入 PATH。
方式一：使用 go install
go install github.com/TencentCloudAgentRuntime/agr-cli/cmd/agr@latest
agr version -o json
方式二：从源码构建
git clone https://github.com/TencentCloudAgentRuntime/agr-cli.git
cd agr-cli
make build
sudo cp agr /usr/local/bin/agr
agr version -o json
agr version -o json 返回 Version、Commit 和 BuildTime 字段，可用于确认当前安装版本。
步骤 2：写入本地凭据
agr init 只写本地 CLI 配置，不会创建远端资源。
export TENCENTCLOUD_SECRET_ID="<your-secret-id>"
export TENCENTCLOUD_SECRET_KEY="<your-secret-key>"
﻿
agr init \\
  --secret-id "$TENCENTCLOUD_SECRET_ID" \\
  --secret-key "$TENCENTCLOUD_SECRET_KEY" \\
  --non-interactive
默认配置文件路径为 ~/.agr/config.toml。若 Home 目录不可写，可显式指定路径：
agr --config /path/to/agr-config.toml init \\
  --secret-id "$TENCENTCLOUD_SECRET_ID" \\
  --secret-key "$TENCENTCLOUD_SECRET_KEY" \\
  --non-interactive
步骤 3：查看当前配置
完成初始化后，用 agr status 检查配置是否已被 CLI 识别。
agr status -o json
返回结果中重点确认以下字段：
Data.ConfigFound
Data.ConfigLoaded
Data.Auth.SecretId.Present
Data.Auth.SecretKey.Present
Data.Region
Data.Domain
如果使用了自定义配置路径，检查时需带上同一个 --config 参数。
步骤 4：诊断鉴权与连通性
当 agr status 已经能看到本地配置，但业务命令仍然失败时，使用 agr doctor 诊断。
agr doctor -o json
agr doctor 输出按检查项组织的结果，常见检查包括：
SecretId
SecretKey
TokenCache
ConfigFilePermission
Connectivity
如果返回 AUTH_FAILED 或其他鉴权类错误，可继续执行：
agr explain AUTH_FAILED -o json
agr explain 返回错误含义、退出码、受影响命令以及建议修复动作。
可选：通过配置文件调整默认值
除命令行参数外，agr 支持从配置文件读取常用默认值。示例结构：
output = "json"
region = "ap-guangzhou"
domain = "tencentags.com"
﻿
[auth]
secret_id = "<your-secret-id>"
secret_key = "<your-secret-key>"
﻿
[sandbox]
default_user = "user"
在自动化脚本中，可以把 output、region 和 domain 写入配置文件以减少重复参数，再用 agr status -o json 复核实际生效值。
当前认证与配置入口
当前 agr CLI 未提供 agr auth 或 agr auth whoami 子命令。认证与本地配置请使用以下入口：
agr init：首次写入本地凭据。
agr config path：查看配置文件路径。
agr config show：查看当前配置值及其来源。
agr config set：更新配置文件中的默认值。
agr status：检查配置是否被 CLI 识别。
agr doctor：诊断鉴权与连通性。
全局参数：--config、--region、--domain、--secret-id、--secret-key
如果您在旧示例或其他材料中看到 agr auth 写法，请以当前 CLI 的 agr --help、agr config --help 和 agr schema -o json 输出为准。
验证结果
当以下条件全部满足时，表示安装与配置已完成：
agr version -o json 能正常返回版本信息。
agr status -o json 显示 ConfigFound: true 且凭据字段为 Present: true。
agr doctor -o json 的 Connectivity 检查通过，或失败原因已明确指向待修复的凭据/网络问题。
清理或回滚
如果只是临时验证本地环境，完成后可删除测试配置并清理环境变量：
rm -f ~/.agr/config.toml
unset TENCENTCLOUD_SECRET_ID
unset TENCENTCLOUD_SECRET_KEY
如果使用了自定义配置路径，请将 ~/.agr/config.toml 替换为实际文件路径。
agr CLI 安装与配置

本页目录：

前提条件

步骤 1：安装 agr CLI

方式一：使用 `go install`

方式二：从源码构建

步骤 2：写入本地凭据

步骤 3：查看当前配置

步骤 4：诊断鉴权与连通性

可选：通过配置文件调整默认值

当前认证与配置入口

验证结果

清理或回滚
