huaweicloud/huaweicloud-devkit

HuaweiCloud DevKit

Discussions
License
CI
npm version
Beta

帮助 AI 编码助手安全、准确地使用华为云——一站式集成云知识、CLI 工具和安全护栏。

支持 OpenCode、Codex、码道（CodeArts Agent）、WorkBuddy、DeepSeek Harness（DSH）、OfficeAce、Hermes、OpenClaw、AtomCode。

前置条件

- Node.js >= 22

国内用户：使用默认 npm 镜像时可能遇到下载缓慢或连接失败的问题，建议配置华为云 npm 镜像：

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

恢复默认镜像：npm config delete registry

镜像滞后：npm 镜像（npmmirror、mirrors.huaweicloud.com）在新版本发布后可能滞后官方源数小时。若安装报 ETARGET 或拿到旧版本，改用官方源安装：

npx --yes --registry=https://registry.npmjs.org huaweicloud-devkit install --target

快速开始

省略 --target 时，安装器会自动检测机器上的 agent：

- 未检测到：交互终端会询问你如何继续（指定 target 安装 / 全部安装 / 接入通用 MCP agent）；非交互终端报错并列出支持列表。
- 检测到单个：直接安装到该 agent。
- 检测到多个：交互终端弹出多选；非交互终端报错并提示 --target  或 --target all。
需要一步全量安装时执行 npx --yes huaweicloud-devkit install --target all（Codex 缺少 CLI 时跳过）。

以下为全局命令（一次性作用于所有 agent）：

npx --yes huaweicloud-devkit version  # 查看 CLI 版本和各 agent 已安装的插件版本
npx --yes huaweicloud-devkit uninstall --target all --clean-global  # 一并删除 KooCLI 与 OBS 配置

OpenCode

npx --yes huaweicloud-devkit install --target opencode

安装后重启会话。

npx --yes huaweicloud-devkit doctor --target opencode
npx --yes huaweicloud-devkit status --target opencode
npx --yes huaweicloud-devkit update --target opencode
npx --yes huaweicloud-devkit uninstall --target opencode
rm -rf ~/.npm/_npx/  # 仅 Linux/macOS；Windows：rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx

Codex

npx --yes huaweicloud-devkit install --target codex

安装后重启 Codex 会话。

codex plugin list  # 验证 huaweicloud-devkit@huaweicloud-devkit 已安装并启用
npx --yes huaweicloud-devkit doctor --target codex
npx --yes huaweicloud-devkit status --target codex
npx --yes huaweicloud-devkit update --target codex
npx --yes huaweicloud-devkit uninstall --target codex

随后在 Codex 中提及 @huaweicloud-devkit，或直接描述华为云任务。

需要 Codex CLI — codex 命令必须在 PATH 中。若 Codex 通过 WindowsApps（Microsoft Store）安装，请使用 --target codex-desktop 替代。运行 codex --version 验证 CLI 可用性。

Codex Desktop

当 Codex CLI 不可用，或 Windows 上通过 WindowsApps 安装 Codex 时，使用此目标。

npx --yes huaweicloud-devkit install --target codex-desktop

安装后重启 Codex Desktop 会话。

npx --yes huaweicloud-devkit doctor --target codex-desktop
npx --yes huaweicloud-devkit status --target codex-desktop
npx --yes huaweicloud-devkit update --target codex-desktop
npx --yes huaweicloud-devkit uninstall --target codex-desktop

随后在新的 Codex Desktop 任务中提及 @huaweicloud-devkit，或直接描述华为云任务。

CodeArts Agent（码道）

npx --yes huaweicloud-devkit install --target codearts

安装后重启会话。

npx --yes huaweicloud-devkit doctor --target codearts
npx --yes huaweicloud-devkit status --target codearts
npx --yes huaweicloud-devkit update --target codearts
npx --yes huaweicloud-devkit uninstall --target codearts

沙箱模式：码道默认沙箱模式会阻止 KooCLI 运行。install-hcloud 自动检测并给出指引——请在码道外终端安装使用 KooCLI，或在码道设置中关闭沙箱模式（设置 → 对话流 → 智能体 终端命令运行模式 → 自动运行）。

CodeArts Work（码道工作空间）

npx --yes huaweicloud-devkit install --target codearts-work

安装后重启会话。

npx --yes huaweicloud-devkit doctor --target codearts-work
npx --yes huaweicloud-devkit status --target codearts-work
npx --yes huaweicloud-devkit update --target codearts-work
npx --yes huaweicloud-devkit uninstall --target codearts-work

CodeArts Work（工作空间，appId: com.codearts.work）使用用户级配置 %USERPROFILE%\.codeartswork\，不创建项目级目录。

WorkBuddy

npx --yes huaweicloud-devkit install --target workbuddy

安装后重启会话。

npx --yes huaweicloud-devkit doctor --target workbuddy
npx --yes huaweicloud-devkit status --target workbuddy
npx --yes huaweicloud-devkit update --target workbuddy
npx --yes huaweicloud-devkit uninstall --target workbuddy

DeepSeek Harness（DSH）

npx --yes huaweicloud-devkit install --target dsh

安装后重启 DSH 会话。

npx --yes huaweicloud-devkit doctor --target dsh
npx --yes huaweicloud-devkit status --target dsh
npx --yes huaweicloud-devkit update --target dsh
npx --yes huaweicloud-devkit uninstall --target dsh

DSH V1 通过 @deepseek-ai/dsh-mcp-client 复用现有 MCP Server。如果安装器提示客户端未检测到，请执行：npx @deepseek-ai/dsh plugin --profile web add @deepseek-ai/dsh-mcp-client。

OfficeAce

npx --yes huaweicloud-devkit install --target officeace

安装后重启 OfficeAce。

npx --yes huaweicloud-devkit doctor --target officeace
npx --yes huaweicloud-devkit status --target officeace
npx --yes huaweicloud-devkit update --target officeace
npx --yes huaweicloud-devkit uninstall --target officeace

Hermes

npx --yes huaweicloud-devkit install --target hermes

安装后重启 Hermes 会话。

npx --yes huaweicloud-devkit doctor --target hermes
npx --yes huaweicloud-devkit status --target hermes
npx --yes huaweicloud-devkit update --target hermes
npx --yes huaweicloud-devkit uninstall --target hermes

卸载说明：Linux 上卸载后执行 rm -rf ~/.npm/_npx/* && npm cache clean --force 确保下次全新安装。Windows 上先关闭所有 Hermes 会话（释放文件锁），卸载后检查 %LOCALAPPDATA%\hermes\config.yaml 是否有 YAML 损坏，如有残留文件手动删除 %LOCALAPPDATA%\hermes\huaweicloud-plugins。
安全钩子（Safety hooks）：安装器会在 config.yaml 中写入 shell hooks 配置（hooks.pre_tool_call），拦截不安全的终端命令，如读取凭据文件、导出环境变量、未审批的 hcloud 写操作。Hermes 首次使用时会弹出同意提示，可批准或设置 hooks_auto_accept: true 自动批准。
MCP Python SDK：安装器会自动安装 Hermes 所需的 mcp Python 包。如果 doctor 显示 [FAIL] Hermes MCP Python SDK，手动执行 pip3 install mcp。
Windows：参见 docs/hermes-windows.md 了解已知问题和解决方法。

OpenClaw

推荐方式 (ClawHub)
openclaw plugins install clawhub:huaweicloud-devkit
openclaw plugins uninstall huaweicloud-devkit
openclaw plugins update huaweicloud-devkit

安装后重启 OpenClaw。如提示安全风险确认，加 --acknowledge-clawhub-risk。

或通过 npx
npx --yes huaweicloud-devkit install --target openclaw
npx --yes huaweicloud-devkit status --target openclaw
npx --yes huaweicloud-devkit update --target openclaw
npx --yes huaweicloud-devkit uninstall --target openclaw
rm -rf ~/.npm/_npx/  # 仅 Linux/macOS；Windows：rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx

AtomCode

npx --yes huaweicloud-devkit install --target atomcode

安装后重启 AtomCode 会话。

npx --yes huaweicloud-devkit doctor --target atomcode
npx --yes huaweicloud-devkit status --target atomcode
npx --yes huaweicloud-devkit update --target atomcode
npx --yes huaweicloud-devkit uninstall --target atomcode

其他 Agent

任何支持 MCP 协议的 Agent，直接使用标准 MCP 配置：

{
"mcpServers": {
"huaweicloud-devkit": {
"command": "npx",
"args": ["-y", "-p", "huaweicloud-devkit", "huaweicloud-devkit-mcp"]
}
}
}

无需预安装 — npx 自动处理一切。

像上面这种手动 MCP 注册方式，请勿在配置里写凭据。HW_ACCESS_KEY/HW_SECRET_KEY 是保留给平台/CI 注入的账号用的（例如 DevSpace 托管的默认账号）——自己的账号统一通过 npx huaweicloud-devkit auth init 配置（唯一入口），会话内切换账号用 huaweicloud_auth_init / huaweicloud_auth_switch MCP 工具。完整凭据解析优先级见 plugins/huaweicloud-core/skills/huaweicloud-cli-and-auth/SKILL.md。

通过 Remote（HTTP）连接

若 Agent 支持 type: "remote"（Streamable HTTP）而非 stdio，可在本地先启动 devkit 的远程 MCP 服务器：

npx --yes huaweicloud-devkit-mcp --transport remote

默认监听 127.0.0.1:9528。随后以远程方式连接（以 opencode 为例）：

{
"mcp": {
"huaweicloud-devkit": {
"type": "remote",
"url": "http://localhost:9528",
"enabled": true,
},
},
}

端口被占用时用 --port  换端口，url 同步修改；需要局域网访问时加 --host 0.0.0.0。remote 服务器不内置鉴权，请勿匿名暴露到公网。

安装 KooCLI

npx --yes huaweicloud-devkit install-hcloud

配置凭据

npx --yes huaweicloud-devkit auth init

一步同步 AK/SK 到 KooCLI、OBS 和沙箱接口——这是唯一入口，切勿把 AK/SK 手写进 Agent 或 shell 配置。

会话内切换账号：使用 MCP 工具 huaweicloud_auth_init（内存态，优先级最高）或 huaweicloud_auth_switch（temporary / persist / clear）。在沙箱/DevSpace 环境中若默认账号经 HW_ACCESS_KEY/HW_SECRET_KEY 注入，单纯 auth init 无法覆盖——需 huaweicloud_auth_switch action=persist 让会话账号生效。

凭据解析优先级（从高到低）：

| #   | 来源                                          | 由谁设置                                                                      |
| --- | --------------------------------------------- | ----------------------------------------------------------------------------- |
| 1   | 运行时（会话）凭据                            | huaweicloud_auth_init / huaweicloud_auth_switch action=temporary          |
| 2   | 带 configuredBySession: true 的 S1 全局文件 | huaweicloud_auth_switch action=persist                                      |
| 3   | 环境变量（HW_ACCESS_KEY/HW_SECRET_KEY）   | 平台/DevSpace 注入的默认账号                                                  |
| 4   | CodeArts / CodeArts Work                      | .codeartsdoer/mcp/mcp_settings.json / .codeartswork/mcp/mcp_settings.json |
| 5   | S1 全局文件（无会话标记）                     | auth init                                                                   |
| 6   | KooCLI profile                                | ~/.hcloud/config.json（仅 KooCLI 命令）                                     |

安全：切勿把自己账号的 AK/SK 写入 MCP 配置的 env 字段——会以明文存储，配置文件提交 git 时即泄密；env 仅用于平台/CI 注入。

完整说明：plugins/huaweicloud-core/skills/huaweicloud-cli-and-auth/SKILL.md。

安装所有 Agent

npx --yes huaweicloud-devkit install --target all

更新所有 Agent

npx --yes huaweicloud-devkit@latest version
npx --yes huaweicloud-devkit@latest update --target all

update 是增量更新——只刷新已安装的文件，不动配置文件。请务必保留 @latest，确保 npm 获取最新版本而非本地缓存的旧版本。

功能特性

- 引导式云操作 — Agent 获得 20+ 常用华为云服务的分步操作指引（ECS、OBS、VPC、RDS、GaussDB、FunctionGraph、APIG、CCE 等）
- 安全优先执行 — 所有写操作需用户明确批准；凭证和密钥自动脱敏
- 执行前风险检查 — 公网暴露、凭证泄露、破坏性操作在执行前即被拦截
- 区域感知 — 自动发现可用区域，创建资源前检查服务可用性
- 沙箱（DevStation） — 临时云端运行环境，部署 Web 应用并即刻获得公网预览地址

支持的服务

ECS、OBS、VPC、IAM、RDS、GaussDB、FunctionGraph、APIG、CCE、SMN/DMS、ModelArts、Cloud Eye、CTS、DEW、Billing、CBR、WAF/AAD、DDS/DCS、Deployment，以及入门指南。

以上为预置指引的服务列表；其余 200+ 华为云服务仍可通过 KooCLI / API / SDK 路由调用（见 capability-discovery 与 cli-and-auth 元技能）。

文档

- 架构
- 安全模型
- Hook 规则模型
- DeepSeek Harness 集成
- 变更记录
- KooCLI 官方文档

贡献者

许可证

本项目基于 Apache-2.0 许可证发布。详见 LICENSE。