零基础安装 HuaweiCloud DevKit 插件全攻略:从零到云资源管理

举报
yd_247939230 发表于 2026/10/16 14:29:52 2026/10/16
【摘要】 本文记录了 HuaweiCloud DevKit 插件的完整安装配置过程,涵盖 KooCLI 安装、凭据配置、隐私协议接受、代金券领取等全流程。适用于 Windows 环境,其他平台同理。一、HuaweiCloud DevKit 是什么HuaweiCloud DevKit 是华为云官方推出的开发者工具包插件,为 AI 编程助手(如 CodeArts、OpenCode 等)提供 39 个 MC...

本文记录了 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 到部署应用,从管理数据库到查看账单,一句话即可完成。开始你的云上之旅吧!🚀

【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。