---
name: tcloud
description: "腾讯云资源管理 Skill（内置 taproxy 代理服务）。当用户需要查询、管理、操作任何腾讯云资源（服务器、数据库、网络、存储、安全、账单等）时，必须先 read_file ~/.openclaw/skills/tcloud/SKILL.md 获取完整操作指引，然后通过 taproxy 的 REST API 执行调用。taproxy 已内置于本 Skill，无需单独安装。注意：tcloud 不是 CLI 命令，必须先读取 SKILL.md。"
metadata:
  {
    "openclaw":
      {
        "emoji": "☁️",
        "always": true,
      },
  }
---

# tcloud — 腾讯云资源管理 Skill

> ⚠️ 凭据使用规则见 AGENTS.md「凭据使用铁律」。核心：**用户选了哪个凭据就只能用哪个，调用失败必须报错给用户，严禁自动换凭据重试。**

当用户提到以下任何场景时，**必须**使用本 Skill：
- 查询/管理腾讯云服务器（CVM）、数据库、网络、存储等资源
- 查看账单、余额、费用
- 管理安全组、密钥、证书
- 操作容器服务、CDN、DNS、云函数等
- 任何涉及腾讯云的操作

---

## 约定

以下文档中 `$SKILL_DIR` 表示本文件所在目录（即读取本文件路径去掉 `/SKILL.md`）。

## 规则

1. **所有腾讯云 API 调用必须通过 taproxy**（`http://127.0.0.1:18900`），禁止直接调用 tccli 或 curl 访问 `*.tencentcloudapi.com`
2. **凭据由 taproxy 管理**，Agent 无需也无法访问 AKSK
3. **每次操作前必须先做健康检查**，确认 taproxy 在线
4. **首次调用使用 `"credential_id": "default"`**，仅在 taproxy 返回 `credential_required: true` 时才**停下来让用户选择凭据**。用户选定后，**只能使用该凭据**，调用失败必须报错给用户，**严禁自动换成其他凭据重试**

---

## 工具 API

所有工具通过 `POST http://127.0.0.1:18900/tools/call` 统一调用。

### 请求格式

⚠️ `credential_id` 是**顶层字段**，与 `tool_name`/`arguments` 同级，**严禁放入 `arguments` 内部**。

```json
{
  "tool_name": "工具名称",
  "arguments": { ... },
  "credential_id": "default"
}
```

### 可用工具

| 工具 | 说明 | 需要 credential_id |
|------|------|--------------------|
| `tencent.cloud.list_services` | 列出腾讯云服务（支持 `domain`/`keyword` 筛选） | ❌ |
| `tencent.cloud.list_actions` | 列出服务的 API 操作（支持 `keyword`/`risk` 筛选） | ❌ |
| `tencent.cloud.describe_action` | 查看 API 的参数文档 | ❌ |
| `proxy.list_credentials` | 列出可用凭据元数据（支持 `category` 过滤） | ❌ |
| `tencent.cloud.invoke` | 调用腾讯云 API | ✅ `"default"` |

### 工具参数速查

**tencent.cloud.list_services**：
- `domain` (可选): security / compute / network / storage / database / monitor / cdn / ai / other
- `keyword` (可选): 关键词搜索

**tencent.cloud.list_actions**：
- `service` **(必填)**: 服务名（如 cvm, kms）
- `keyword` (可选): 关键词筛选
- `risk` (可选): safe / moderate / dangerous

**tencent.cloud.describe_action**：
- `service` **(必填)**: 服务名
- `action` **(必填)**: 操作名

**proxy.list_credentials**：
- `category` (可选): sts（腾讯云 AKSK）/ access（SSH/数据库）

**tencent.cloud.invoke**：
- `service` **(必填)**: 服务名（如 cvm, billing）
- `action` **(必填)**: 操作名（如 DescribeInstances）
- `region` (可选): 地域代码（如 ap-guangzhou）
- `params` (可选): 业务参数 JSON 对象

---

## 工作流（必须严格遵循）

**当用户提出任何腾讯云操作请求时，按以下阶段执行：**

### 阶段 1：健康检查

```bash
curl -s http://127.0.0.1:18900/health
```

- ✅ 返回 `{"status":"healthy", ...}` → 进入阶段 2
- ❌ 失败或无响应 → 尝试启动 taproxy：

```bash
$SKILL_DIR/taproxy &
sleep 3
curl -s http://127.0.0.1:18900/health
```

- 启动成功 → 进入阶段 2
- 仍然失败 → 告知用户错误信息，参考下方「启动失败排查」

### 阶段 2：确定地域 + 执行 API 调用

**2a. 确定 service/action**：如果不确定用哪个，先用 `list_services` → `list_actions` → `describe_action` 逐步探索。

**2b. 确定地域（region）**：大多数资源类 API（如 CVM、CDB、VPC）需要指定地域，处理规则如下：

| 场景 | 处理方式 |
|------|---------|
| 用户明确指定了地域（如"广州的服务器"） | 查下方地域速查表，直接传对应的 `region` 代码 |
| **用户未指定地域（无论查询还是操作）** | **必须先询问用户**选择地域，提供地域选项列表（含"全部地域"选项），等待用户回复后再执行 |
| API 不需要地域（如 billing、cam） | 不传 `region` 参数 |
| 用户提到的地域不在速查表中 | 调用 `DescribeRegions` 动态查询（见地域速查表 > 动态查询） |

**地域选择提示格式**：当用户未指定地域时，向用户展示如下选项：
```
请选择要查询的地域：
1. 华南（广州）
2. 华东（上海）
3. 华北（北京）
4. 华东（南京）
5. 西南（成都）
6. 西南（重庆）
7. 中国香港
8. 新加坡
9. 全部地域（自动遍历以上所有地域）
请回复序号或地域名称。
```

**多地域查询**：仅当用户选择"全部地域"时，才遍历以下常用地域发起查询，合并结果：
`ap-guangzhou`、`ap-shanghai`、`ap-beijing`、`ap-nanjing`、`ap-chengdu`、`ap-chongqing`、`ap-hongkong`、`ap-singapore`。
- 对每个地域发起一次 API 调用，将有结果的地域合并展示
- 无结果的地域跳过，不展示
- 在结果中标注每个资源所在的地域

> ⚠️ **严禁以下行为**：
> - 禁止在用户未指定地域时自动选择某个地域（如默认用 ap-guangzhou）
> - 禁止在用户未指定地域时自动遍历所有地域（必须先问用户）
> - 禁止跳过地域选择步骤直接执行 API 调用

**2c. 执行调用**：

```bash
curl -X POST http://127.0.0.1:18900/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "tencent.cloud.invoke",
    "arguments": {
      "service": "cvm",
      "action": "DescribeInstances",
      "region": "ap-guangzhou",
      "params": {}
    },
    "credential_id": "default"
  }'
```

### 阶段 3：处理响应

检查返回的 JSON：

**情况 A：成功**（`"success": true`）
- 向用户展示结果，任务完成 ✅

**情况 B：需要凭据选择**（`"success": false, "credential_required": true`）
- taproxy 返回可用凭据列表，说明默认凭据不可用
- 响应格式示例：

```json
{
  "success": false,
  "error": "当前凭据 default 不可用...",
  "credential_required": true,
  "credentials": [
    {"id": "crd-875815e3", "name": "国际站线上AK", "type": "sts"},
    {"id": "crd-a313396b", "name": "测试AK", "type": "sts"}
  ]
}
```

- **处理步骤（必须严格遵循，不可跳过）**：
  1. **立即停止所有 API 调用**，不要继续尝试
  2. 向用户展示凭据列表（**必须展示 API 返回的全部凭据，禁止按 name 去重，因为同名凭据的 id 不同、权限不同**），格式如下：
     ```
     检测到多个云凭据，请选择要使用的凭据：
     1. [crd-875815e3] 国际站线上AK (sts)
     2. [crd-a313396b] 测试AK (sts)
     请回复序号或凭据 ID。
     ```
  3. **等待用户回复**，不要自行猜测或自动选择
  4. 用用户选中的 **单个** `credential_id` 重新执行 API 调用
  5. 如果使用用户选中的凭据调用失败，**必须将错误信息原样报给用户**，由用户决定下一步操作

> ⚠️ **严禁以下行为**：
> - 禁止自动遍历所有凭据逐个尝试
> - 禁止不询问用户就自行选择凭据
> - **禁止在用户选定凭据后，因调用失败而自动切换到其他凭据**（必须报错给用户）
> - 禁止在一次请求中传入多个 credential_id
> - `credential_id` 字段只接受**单个字符串**值（如 `"crd-875815e3"`），不接受数组或逗号分隔

**情况 C：其他错误**（`"success": false`，无 `credential_required`）
- **必须将错误信息原样展示给用户**
- 如果错误是**权限类**（如 `UnauthorizedOperation`），在展示错误后**重新列出凭据列表**，让用户选择其他凭据重试：
  ```
  ⚠️ 凭据 [crd-xxx] xxx 没有执行该操作的权限，错误信息：...
  
  是否要换一个凭据重试？请选择：
  1. [crd-yyy] ...
  2. [crd-zzz] ...
  或回复"取消"放弃操作。
  ```
- 如果是其他类型错误（如 `InvalidParameter`），直接展示错误信息即可
- ⚠️ **严禁自动切换凭据重试**：必须等用户重新选择后才能使用新凭据调用

---

## 启动失败排查

| 错误 | 原因 | 解决方案 |
|------|------|---------|
| `Connection refused` | taproxy 未运行 | `$SKILL_DIR/taproxy &` |
| `address already in use` | 端口 18900 被占用 | `lsof -ti :18900 \| xargs kill` 或 `fuser -k 18900/tcp` 后重启 |
| `permission denied` | 无执行权限 | `chmod +x $SKILL_DIR/taproxy` |
| 启动时报错 | 查看详细日志 | `tail -f ~/.openclaw/logs/taproxy.log` |

---

## 地域速查表

### 中国大陆

| 地域 | 代码 |
|------|------|
| 华南（广州） | `ap-guangzhou` |
| 华东（上海） | `ap-shanghai` |
| 华东（南京） | `ap-nanjing` |
| 华北（北京） | `ap-beijing` |
| 西南（成都） | `ap-chengdu` |
| 西南（重庆） | `ap-chongqing` |

### 港澳台及亚太

| 地域 | 代码 |
|------|------|
| 中国香港 | `ap-hongkong` |
| 新加坡 | `ap-singapore` |
| 曼谷 | `ap-bangkok` |
| 雅加达 | `ap-jakarta` |
| 首尔 | `ap-seoul` |
| 东京 | `ap-tokyo` |

### 欧美及其他

| 地域 | 代码 |
|------|------|
| 硅谷 | `na-siliconvalley` |
| 弗吉尼亚 | `na-ashburn` |
| 法兰克福 | `eu-frankfurt` |
| 圣保罗 | `sa-saopaulo` |
| 利雅得 | `me-saudi-arabia` |

### 动态查询

如果用户提到的地域不在上表中，或需确认某产品在特定地域是否可用：

```bash
curl -X POST http://127.0.0.1:18900/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "tencent.cloud.invoke",
    "arguments": {
      "service": "region",
      "action": "DescribeRegions",
      "params": {"Product": "cvm"}
    },
    "credential_id": "default"
  }'
```

> 将 `Product` 替换为实际的服务名（如 `cvm`、`cdb`、`redis`）。

---

## 安全机制

1. **凭据自动注入**: taproxy 管理所有腾讯云凭据，Agent 无法访问或暴露 AKSK
2. **完整审计**: 所有 API 调用均有详细的审计日志记录
3. **风险分级**: 危险操作标记为 `dangerous`，某些操作需要显式确认
4. **完全隔离**: 所有敏感信息在 taproxy 内部处理，不经过 LLM 上下文