华为云开发套件 huaweicloud/huaweicloud-devkit

HuaweiCloud DevKit

帮助 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>

快速开始

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

- 未检测到：交互终端会询问你如何继续（指定 target 安装 / 全部安装 / 接入通用 MCP agent）；非交互终端报错并列出支持列表。
- 检测到单个：直接安装到该 agent。
- 检测到多个：交互终端弹出多选；非交互终端报错并提示 --target <agent> 或 --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 获取最新版本而非本地缓存的旧版本。

配置代理

npx --yes huaweicloud-devkit proxy init # 配置代理（交互式）
npx --yes huaweicloud-devkit proxy show # 查看生效的代理设置
npx --yes huaweicloud-devkit proxy clear # 删除代理配置

为连接华为云服务配置 HTTP/HTTPS 代理（如企业内网环境）。配置保存在 ~/.config/huaweicloud/proxy.json。

环境变量 HTTPS_PROXY、HTTP_PROXY、NO_PROXY 优先级高于文件配置——可使用 proxy show 查看最终生效的设置。

遥测

HuaweiCloud DevKit 收集匿名遥测数据，以了解使用模式并改进插件。遥测默认开启。

收集哪些数据

- 安装 ID — 基于机器指纹（主机名 + MAC 地址 + OS 类型 + home 目录）生成的 SHA-256 哈希。原始值不会被发送或存储。
- 用户哈希 — 服务端生成的用户标识哈希（由华为云后端 check-user / generatorUserIDHash API 生成）。本地缓存后随每次事件发送，非本地 PII 派生。
- 插件版本 — 已安装的 huaweicloud-devkit 版本。
- Agent harness — 正在运行的 AI 编码助手（如 opencode、codex、codearts）。
- Agent 版本 — Agent 版本号。
- OS 类型和版本 — 如 Linux、Darwin、Windows_NT。
- Capability — 事件触发方式：mcp（MCP 工具调用）或 cli（CLI 命令），由事件 key 派生。
- 事件类型 — 发生了什么，如 plugin:install（安装）、plugin:first_use（首次使用）、dau:active_today（日活）、tool:<工具名>（工具调用）、skill:retrieve（技能加载）、sandbox:connect（沙箱连接）。
- 事件值 — 简短的脱敏字符串（最长 255 字符，换行符/制表符已清除）。工具事件通常为 1；技能加载事件为技能名称。

不收集哪些数据

- 不收集 AK/SK、访问密钥或任何凭据
- 不收集用户输入、提示词或代码内容
- 不收集 IP 地址
- 不收集个人可识别信息（PII）
- 不收集文件路径或项目名称

数据如何传输

事件先在内存中排队，然后每 60 秒批量（每批最多 100 条）通过 HTTP POST 发送到华为云遥测端点。传输过程遵循你的代理配置。发送失败最多重试 3 次后丢弃。

禁用遥测（Opt-Out）

设置环境变量：

export HUAWEICLOUD_DEVKIT_TELEMETRY=off

设置为 off 后，不会收集或传输任何遥测事件。

调试模式

如需记录遥测活动以供排查：

export HUAWEICLOUD_DEVKIT_DEBUG=true

调试日志写入插件的 telemetry/telemetry-debug.log 文件。

功能特性

- 引导式云操作 — 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。