零基础安装 HuaweiCloud DevKit 插件全攻略:从零到云资源管理
本文记录了 HuaweiCloud DevKit 插件的完整安装配置过程,涵盖 KooCLI 安装、凭据配置、隐私协议接受、代金券领取等全流程。适用于 Windows 环境,其他平台同理。
一、HuaweiCloud DevKit 是什么
HuaweiCloud DevKit 是华为云官方推出的开发者工具包插件,为 AI 编程助手(如 CodeArts、OpenCode 等)提供 39 个 MCP 工具,覆盖华为云全栈服务:
| 能力域 | 涵盖服务 |
|---|---|
| 云资源管理 | ECS、OBS、RDS、VPC、CCE、GaussDB、DDS、DCS 等 |
| 安全与密钥 | IAM、DEW/KMS/CSMS、WAF、AAD |
| 消息与通知 | SMN、DMS(Kafka/RabbitMQ/RocketMQ) |
| 部署与运维 | CloudDeploy、FunctionGraph、Sandbox |
| 监控与审计 | CloudEye(CES)、CTS |
| 账单与成本 | BSS 账单查询、代金券领取 |
| 文档与诊断 | 官方文档搜索、错误码解释、服务目录 |
安装完成后,你只需用自然语言对 AI 助手说话,即可管理华为云资源——无需记忆任何 CLI 命令。
二、环境准备
2.1 必要条件
| 条件 | 要求 |
|---|---|
| Node.js | v18+(推荐 v22+) |
| npm/npx | 随 Node.js 安装 |
| 操作系统 | Windows / macOS / Linux |
| 华为云账号 | 已注册,能登录控制台 |
| AK/SK | 华为云访问密钥 |
2.2 检查 Node.js 环境
node --version # 确认 v18+
npx --version # 确认 npx 可用
如果未安装 Node.js,前往 nodejs.org 下载 LTS 版本。
2.3 准备华为云访问密钥(AK/SK)
打开华为云控制台:访问密钥管理页
点击「新增访问密钥」→ 完成身份验证
下载凭证文件(内含 AK 和 SK)
⚠️ SK 只在创建时显示一次,请务必妥善保存下载的凭证文件。
三、安装全流程
安装分为 4 个阶段,预计耗时 5-10 分钟。
阶段 1: 安装 KooCLI (hcloud) ── 约 2-3 分钟(含下载)
阶段 2: 接受隐私协议 ── 约 10 秒
阶段 3: 配置凭据 (AK/SK) ── 约 1 分钟
阶段 4: 验证安装 ── 约 30 秒
阶段 1:安装 KooCLI(hcloud)
KooCLI 是华为云命令行工具,DevKit 插件的 CLI 类操作依赖它。
在终端中执行:
npx huaweicloud-devkit install-hcloud
安装过程输出示例:
╔══════════════════════════════════════════════╗
║ HuaweiCloud DevKit v1.1.8 ║
║ https://github.com/huaweicloud ║
╚══════════════════════════════════════════════╝
Installing KooCLI (hcloud)...
[Windows] Auto-installing to C:\Users\<用户名>\hcloud...
Downloading https://cn-north-4-hdn-koocli.obs.cn-north-4.myhuaweicloud.com/cli/7.2.12/huaweicloud-cli-windows-amd64.zip...
Extracting...
Adding to user PATH...
Added to user PATH (deduped): C:\Users\<用户名>\hcloud
Install complete.
各平台安装路径:
| 平台 | 安装路径 |
|---|---|
| Windows | C:\Users<用户名>\hcloud\hcloud.exe |
| Linux | ~/.local/bin/hcloud |
| macOS | /usr/local/bin/hcloud |
💡 如果命令超时:KooCLI 安装包约 44MB,下载可能需要 1-3 分钟。可使用后台方式运行:
# Linux/macOS 后台运行
nohup npx huaweicloud-devkit install-hcloud > install.log 2>&1 &
# Windows 用户可直接在前台等待,或在新终端窗口中执行。
阶段 2:接受隐私协议
KooCLI 首次运行时需要接受隐私协议。
在终端中执行:
# Windows - 如果 PATH 未刷新,先手动添加
$env:Path += ";C:\Users\<用户名>\hcloud"
# 运行 version 命令
hcloud version
会看到如下提示:
KooCLI即将通过https协议连接互联网,以便调用相关云服务,实现云资源管理功能.
网关及服务会记录用户访问日志等信息.该数据的收集、存储及销毁等操作遵循
《隐私政策声明》(地址:https://www.huaweicloud.com/declaration/sa_prp.html).
同意并继续使用(y)/不同意并退出(N):
输入 y 并回车,即可接受协议。
⚠️ PATH 未刷新问题:安装后如果提示 hcloud : 无法将"hcloud"项识别为 cmdlet,说明当前终端的 PATH 未刷新。解决方法:
方法 A(临时):执行 $env:Path += “;C:\Users<用户名>\hcloud”(PowerShell)
方法 B(推荐):关闭并重新打开终端
阶段 3:配置凭据(AK/SK)
这一步将你的华为云 AK/SK 配置到 KooCLI,使插件能以你的身份调用云服务 API。
在终端中执行:
npx huaweicloud-devkit auth init
按提示依次输入:
HuaweiCloud DevKit Unified Authentication Setup
Access Key ID (AK): ← 输入你的 AK,回车
Secret Access Key (SK): ← 输入你的 SK,回车
Security Token (optional, press Enter to skip): ← 直接回车跳过(除非使用临时凭证)
Project ID auto-set: <自动获取的Project ID>
Credentials synchronized.
看到 Credentials synchronized. 即表示凭据配置成功。
🔒 安全提示:
永远不要用 hcloud configure set --cli-access-key=xxx 方式配置(AK/SK 会留在 shell 历史记录中)
始终使用 npx huaweicloud-devkit auth init 交互式配置
凭据会加密存储在本地凭据库中(S2 加密)
阶段 4:验证安装
配置完成后,建议验证所有组件状态。
方式一:通过 AI 助手验证(推荐)
对 AI 助手说:
“检查一下华为云 DevKit 插件的安装状态”
AI 助手会调用 check_cli 和 auth_status 工具,返回完整状态报告。
方式二:通过命令行验证
# 验证 KooCLI 版本
hcloud version
# 应输出:当前KooCLI版本:7.2.12
# 验证凭据配置
npx huaweicloud-devkit doctor
期望的最终状态:
| 组件 | 期望状态 |
|---|---|
| 插件(MCP server) | 已安装,39 个工具可用 |
| KooCLI (hcloud) | installed: true |
| 凭据 | authenticated: true |
| KooCLI profile | default 已创建并同步 |
| OBS 配置 | 已就绪 |
| Agent 注册 | 已注册(如 codearts、opencode 等) |
四、代金券领取
安装完成后,华为云提供两类代金券可领取:
4.1 激励代金券(首次使用福利)
首次使用插件可领取一张华为云代金券(一人一次)
领取方式:对 AI 助手说「帮我领取一张华为云代金券」
AI 助手会先查询领取状态(voucher_status),若未领取则自动领取(voucher_claim)。
⚠️ 注意:激励代金券按月发放,每月总额度有限。如果本月额度用完,需下月再试。
4.2 赛事代金券(华为开发者大赛·小红书 skill 创新赛)
前提条件:需先完成赛事报名。
领取方式:对 AI 助手说「帮我领取华为开发者大赛·小红书 skill 创新赛华为云代金券」
AI 助手会调用 competition_voucher_claim 工具领取。领取成功后返回代金券 ID 和金额。
💡 赛事代金券与激励代金券额度独立,互不影响。
五、安装验证
安装完成后,完整的状态检查应包含以下内容:
✅ 插件(MCP server,39 个工具)已安装
✅ 凭据已保存(持久化,加密存储)
✅ KooCLI (hcloud v7.2.12) 已安装
✅ KooCLI profile=default 已创建并同步凭据
✅ OBS 已配置
✅ Project ID 自动获取
✅ Agent 已注册(codearts/opencode 等)
如果任何一项未就绪,根据具体组件排查:
| 问题 | 解决方案 |
|---|---|
| KooCLI 未安装 | 重新执行 npx huaweicloud-devkit install-hcloud |
| hcloud 不在 PATH | 重启终端,或手动添加 PATH |
| 隐私协议未接受 | 运行 hcloud version,输入 y |
| 凭据未配置 | 执行 npx huaweicloud-devkit auth init |
| KooCLI profile 未创建 | 同上,执行 auth init |
| 凭据不一致 | 执行 npx huaweicloud-devkit auth sync 或重新 auth init |
六、开始使用
安装完成后,无需记忆任何命令,直接用自然语言与 AI 助手对话即可。
6.1 常用场景示例
| 你想做的事 | 对 AI 助手说 |
|---|---|
| 部署 Web 应用 | “帮我把这个项目部署到华为云” |
| 沙箱预览 | “用沙箱部署预览我的前端项目” |
| 管理 ECS | “列出我的 ECS 实例” / “创建一台 ECS” |
| 管理 OBS | “创建一个 OBS 桶” / “配置静态网站托管” |
| 管理 RDS | “查看我的 RDS 实例” |
| 网络配置 | “创建 VPC 和子网” |
| 容器集群 | “创建 CCE 集群” |
| 查看账单 | “查询我本月的华为云账单” |
| 搜索文档 | “搜索 OBS 生命周期配置文档” |
| 排查错误 | “解释这个错误码:xxx” |
6.2 只读探索命令
初次使用建议先尝试只读命令熟悉功能:
"列出华为云所有区域"
"查看我的 KooCLI 配置信息"
"华为云有哪些服务"
七、常见问题
Q1: npx huaweicloud-devkit install-hcloud 执行超时
原因:KooCLI 安装包约 44MB,下载耗时较长。
解决:
确保网络通畅,可访问 cn-north-4.myhuaweicloud.com
使用后台方式运行(Linux/macOS):nohup npx huaweicloud-devkit install-hcloud > install.log 2>&1 &
查看安装日志:~/.config/huaweicloud/logs/koocli-install.log
Q2: hcloud 命令不识别(CommandNotFoundException)
原因:安装后 PATH 环境变量未刷新到当前终端会话。
解决:
PowerShell 临时方案:$env:Path += “;C:\Users<用户名>\hcloud”
永久方案:关闭并重新打开终端
备选方案:使用完整路径 C:\Users<用户名>\hcloud\hcloud.exe
Q3: auth init 提示输入 AK 后无响应
原因:命令是交互式的,正在等待输入。
解决:这不是报错,正常输入 AK 并回车,然后输入 SK 并回车即可。SQLite ExperimentalWarning 是 Node.js 警告,可忽略。
Q4: 沙箱环境无法接受隐私协议
原因:沙箱环境无法交互式输入,且可能没有创建配置目录的权限。
解决:在非沙箱的真实终端中执行 hcloud version 并输入 y。
Q5: 代金券领取提示"本月额度已用完"
原因:激励代金券按月发放,全国总额度有上限。
解决:下月再试。赛事代金券额度独立,可单独领取。
Q6: 已有凭据保存在 vault 中,还需要重新输入 AK/SK 吗?
需要。vault 中的凭据用于 MCP 工具调用,但 KooCLI 需要单独创建 profile。执行 npx huaweicloud-devkit auth init 会同时同步到两者。
八、总结
安装流程图
┌─────────────────────────────────────────────────────────┐
│ HuaweiCloud DevKit 安装流程 │
└─────────────────────────────────────────────────────────┘
[准备阶段]
│
├── 1. 安装 Node.js (v18+)
├── 2. 创建华为云 AK/SK
│
▼
[安装阶段]
│
├── 3. npx huaweicloud-devkit install-hcloud
│ └─ 下载并安装 KooCLI (hcloud v7.2.12)
│
├── 4. hcloud version → 输入 y 接受隐私协议
│
├── 5. npx huaweicloud-devkit auth init
│ └─ 输入 AK/SK → 凭据同步
│
▼
[验证阶段]
│
├── 6. check_cli → installed: true ✅
├── 7. auth_status → authenticated: true ✅
├── 8. auth_sync → profile=default synced ✅
│
▼
[完成 🎉]
│
├── 39 个 MCP 工具可用
├── hcloud CLI 可用
└── 自然语言管理华为云资源
关键要点回顾
KooCLI 是核心依赖:插件 MCP 工具中涉及 CLI 操作的功能都依赖 hcloud
auth init 是关键步骤:同时配置 vault 凭据和 KooCLI profile
隐私协议必须接受:首次运行 hcloud 需交互式输入 y
PATH 需要刷新:安装后重启终端或手动添加 PATH
安全第一:始终用 auth init 交互式配置,不在命令行明文传 AK/SK
代金券分两类:激励代金券(按月额度)和赛事代金券(独立额度)
写在最后:安装完成后,你拥有了一个能通过自然语言管理华为云全栈资源的 AI 助手。从创建 ECS 到部署应用,从管理数据库到查看账单,一句话即可完成。开始你的云上之旅吧!🚀
- 点赞
- 收藏
- 关注作者
评论(0)