一行命令搞定华为云开发环境：HuaweiCloud DevKit 安装配置实战

本文记录了在 DevSpace 沙箱环境中，从零开始安装配置 HuaweiCloud DevKit 的完整过程，包括 KooCLI 安装、临时凭证配置、踩坑记录（SecurityToken 问题）及验证方法。适合想在云上快速搭建开发环境的开发者参考。

前言

HuaweiCloud DevKit 是华为云官方推出的 AI 编码代理集成工具包，它能帮助 AI 编码代理安全、准确地使用华为云——一个集成即可获得云知识、CLI 工具和安全护栏。支持 OpenCode、Codex、CodeArts Agent、DeepSeek Harness、Hermes 等多种代理。

本文实战环境：

• 操作系统：Linux (arm64)
• Node.js：v22.23.3
• npm：v10.9.9
• 区域：cn-north-4

一、环境准备

1.1 检查 Node.js 版本

DevKit 要求 Node.js >= 22，先确认环境：

node --version
npm --version

确认输出 v22.23.3 和 10.9.9，满足要求。

中国大陆用户：如果 npm 下载慢，可以配置华为云 npm 镜像：

npm config set registry https://mirrors.huaweicloud.com/repository/npm/

1.2 检查已安装的 AI 编码代理

DevKit 的核心功能是将云能力集成到 AI 编码代理中。支持的目标包括：

二、安装 KooCLI

KooCLI（hcloud）是华为云命令行工具，DevKit 通过它与华为云 API 交互。

npx --yes huaweicloud-devkit install-hcloud

安装过程会自动下载对应平台的二进制文件：

Installing KooCLI (hcloud)...
[Linux] Auto-installing to /root/.local/bin...
  Downloading hcloud-cli-linux-arm64.tar.gz...
  Extracting...
  Installing...
Install complete.

验证安装：

export PATH="$PATH:/root/.local/bin"
hcloud version

输出 当前KooCLI版本:7.2.2，安装成功。

三、配置凭证（关键步骤）

3.1 了解凭证来源

在 DevSpace 等托管环境中，华为云会通过环境变量注入临时凭证：

• HW_ACCESS_KEY — 访问密钥 ID
• HW_SECRET_KEY — 访问密钥
• HW_SECURITY_TOKEN — 安全令牌（临时凭证必备）

3.2 踩坑：auth init 未处理 SecurityToken

官方推荐使用 auth init 一键配置凭证：

npx --yes huaweicloud-devkit auth init

但在含有临时安全令牌的环境中，auth init 不会自动写入 SecurityToken，导致 KooCLI 身份验证失败：

获取账号ID失败: Incorrect IAM authentication information: Unauthorized

3.3 解决方案：手动配置完整凭证

删除有问题的配置，重新设置包含 SecurityToken 的完整凭证：

# 删除旧配置
hcloud configure delete --cli-profile=default

# 重新配置（包含 SecurityToken）
hcloud configure set \
  --cli-access-key="$HW_ACCESS_KEY" \
  --cli-secret-key="$HW_SECRET_KEY" \
  --cli-security-token="$HW_SECURITY_TOKEN" \
  --cli-region=cn-north-4

设置中文模式（BSS 计费服务要求）：

hcloud configure set --cli-lang=cn

3.4 验证凭证

hcloud STS GetCallerIdentity

成功输出：

{
  "account_id": "2ed6b82793e449619dd218720e8a5ed1",
  "principal_urn": "iam::2ed6b82793e449619dd218720e8a5ed1:user:migeluola",
  "principal_id": "313c0c1b41f0449482373bb186e82835"
}

凭证配置成功！

3.5 设置 Project ID

查询项目列表并设置 Project ID：

hcloud IAM KeystoneListProjects

找到 cn-north-4 对应的项目 ID，设置：

hcloud configure set --cli-project-id=<your_project_id>
hcloud configure set --cli-domain-id=<your_domain_id>

四、验证：查询账户余额和代金券

配置完成后，用实际的 BSS 计费 API 验证整个链路是否通畅。

4.1 查询账户余额

hcloud BSS ShowCustomerAccountBalances --cli-region=cn-north-1 --cli-output=json

注意：BSS 计费服务的 endpoint 固定为 cn-north-1，不能替换为其他区域。

4.2 查询代金券交易记录

hcloud BSS ListCustomerCouponChangeRecords \
  --balance_type=BALANCE_TYPE_COUPON \
  --cli-region=cn-north-1 \
  --cli-output=json \
  --limit=10

参数坑：balance_type 的值是枚举字符串 BALANCE_TYPE_COUPON，不是数字 1 或 2。

五、运行诊断

npx --yes huaweicloud-devkit doctor

诊断结果会检查：Node.js 版本、MCP 服务器、运行时依赖、安全策略、KooCLI、凭证配置、Skills 等。

六、凭证解析优先级

DevKit 的凭证解析有 6 级优先级（从高到低）：

在 DevSpace 环境中，环境变量（优先级 3）已注入凭证，但写入 KooCLI 配置（优先级 6）时需要完整携带 SecurityToken。

总结

踩坑总结

1. SecurityToken 缺失：auth init 在临时凭证环境中不自动写入 SecurityToken，需手动 hcloud configure set 补全
2. BSS 区域固定：所有 BSS API 调用必须使用 --cli-region=cn-north-1
3. balance_type 枚举值：代金券查询参数用 BALANCE_TYPE_COUPON，不是数字
4. 中文模式：BSS 计费服务要求 --cli-lang=cn

本文基于 HuaweiCloud DevKit v1.1.12 和 KooCLI v7.2.2 的实际操作整理。更多详情请参考 DevKit 官方文档。