HuaweiCloud DevKit (Community Preview)

HuaweiCloud DevKit

中文 | English

帮助 AI 编码 Agent 安全、准确地使用 Huawei Cloud——通过一次集成，为 Agent 提供云知识、CLI 工具和安全防护。

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

前置条件

• Node.js >= 22

中国大陆用户：如果默认 npm registry 下载缓慢或连接出现问题，请配置 Huawei Cloud npm 镜像：

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

恢复默认 registry：npm config delete registry

镜像延迟：发布新版本后，npm 镜像（npmmirror、mirrors.huaweicloud.com）可能会比官方 registry 延迟数小时。如果安装时出现 ETARGET 错误，或安装到较旧版本，请改用官方 registry 安装：

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

快速开始

如果省略 --target，安装程序会自动检测机器上的 Agent：

• 未检测到：交互式终端会询问你的选择（安装到一个 指定目标 / 安装到所有目标 / 配置通用 MCP Agent）； 非交互式 shell 会报错并列出受支持的目标。
• 检测到一个：直接安装到该目标。
• 检测到多个：交互式终端会显示多选列表； 非交互式 shell 会报错，并提示使用 --target <agent> / --target all。 如需一次性完成完整设置，请运行 npx --yes huaweicloud-devkit install --target all （如果缺少 Codex CLI，则会跳过 Codex）。

以下命令是全局命令（会应用于所有 Agent）：

npx --yes huaweicloud-devkit version  # print CLI version and installed plugin versions per agent
npx --yes huaweicloud-devkit uninstall --target all --clean-global  # also remove KooCLI + OBS config

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  # verify huaweicloud-devkit@huaweicloud-devkit is installed and enabled
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，或直接描述你的 Huawei Cloud 任务。

需要 Codex CLI——codex 命令必须位于 PATH 中。如果 Codex 是通过 WindowsApps（Microsoft Store）安装的，请改用 --target codex-desktop。运行 codex --version 验证 CLI 是否可用。

Codex Desktop

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

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，或直接描述你的 Huawei Cloud 任务。

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

沙箱模式：CodeArts 默认启用沙箱模式，会阻止 KooCLI。install-hcloud 会检测到此情况并说明如何解决——在沙箱终端之外安装 KooCLI，或在 CodeArts 设置中禁用沙箱模式（Settings → Chats → Agents Terminal Command Running Mode → Auto Running）。

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（CodeArts Space，appId：com.codearts.work）使用用户级配置，路径为 %USERPROFILE%\.codeartswork\。不会创建项目级 .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 服务。如果安装程序提示未检测到客户端，请运行：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 中仍有文件时手动删除该目录。 安全钩子：安装程序会配置 Hermes shell 钩子（config.yaml → hooks.pre_tool_call），用于拦截不安全的终端命令，例如读取凭据文件、转储环境变量和未经批准的 hcloud 写入操作。Hermes 首次会显示同意提示；请批准，或在 config.yaml 中设置 hooks_auto_accept: true 以自动接受。 MCP Python SDK：安装程序会自动安装 Hermes 用于发现 MCP 工具所需的 mcp Python 包。如果在 doctor 中看到 [FAIL] Hermes MCP Python SDK，请手动运行 pip3 install mcp。 Windows：已知问题和解决方法请参阅 docs/hermes-windows.md。

OpenClaw

# Recommended (ClawHub)
openclaw plugins install clawhub:huaweicloud-devkit
openclaw plugins uninstall huaweicloud-devkit
openclaw plugins update huaweicloud-devkit

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

# Or via 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 都可以使用标准配置：

{
  "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。

通过远程（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,
    },
  },
}

如果 9528 端口已被占用，请使用 --port <port> 并相应更新 url；如需允许局域网访问，请添加 --host 0.0.0.0。远程服务没有内置身份验证 — 请勿在没有身份验证的情况下将其暴露到公共互联网。

安装 KooCLI

npx --yes huaweicloud-devkit install-hcloud

配置凭据

npx --yes huaweicloud-devkit auth init

一步即可将 AK/SK 同步到 KooCLI、OBS 和沙箱 API——这是唯一入口。切勿将 AK/SK 硬编码到 Agent 或 shell 配置中。

运行时切换账户（在 Agent 会话中）：使用 MCP 工具 huaweicloud_auth_init（内存中，优先级最高）或 huaweicloud_auth_switch（操作：temporary / persist / clear）。在通过 HW_ACCESS_KEY/HW_SECRET_KEY 注入默认账户的沙箱/DevSpace 环境中，直接执行 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 配置文件	~/.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    # configure proxy (interactive)
npx --yes huaweicloud-devkit proxy show    # show effective proxy settings
npx --yes huaweicloud-devkit proxy clear   # remove proxy configuration

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

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

遥测

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

我们收集的信息

• 安装 ID — 根据机器指纹（主机名 + MAC 地址 + OS 类型 + 主目录）生成的 SHA-256 哈希。原始值绝不会发送或存储。
• 用户哈希 — 由服务器生成的用户标识符哈希（通过 Huawei Cloud 后端 check-user / generatorUserIDHash API 生成）。该值会缓存在本地，并随每个事件发送；它并非根据任何本地 PII 生成。
• 插件版本 — 已安装的 huaweicloud-devkit 版本。
• Agent 执行环境 — 正在运行的 AI 编码 Agent（例如 opencode、codex、codearts）。
• Agent 版本 — Agent 的版本字符串。
• OS 类型和版本 — 例如，Linux、Darwin、Windows_NT。
• 能力 — 事件的触发方式：mcp（MCP 工具调用）或 cli（CLI 命令），根据事件键生成。
• 事件类型 — 发生的事件，例如 plugin:install、plugin:first_use、dau:active_today（日活跃）、tool:<tool_name>、skill:retrieve、sandbox:connect。
• 事件值 — 简短的净化字符串（最多 255 个字符，并移除换行符和制表符）。对于工具事件，该值通常为 1；对于技能检索事件，该值为技能名称。

我们不收集的信息

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

数据传输方式

事件会在内存中排队，每 60 秒通过 HTTP POST 向 Huawei Cloud 的遥测终端节点分批发送（每批最多 100 个事件）。传输会遵循你的代理配置。请求失败时最多重试 3 次，之后将丢弃。

禁用遥测（选择退出）

设置环境变量：

export HUAWEICLOUD_DEVKIT_TELEMETRY=off

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

调试模式

如需记录遥测活动以便排查问题：

export HUAWEICLOUD_DEVKIT_DEBUG=true

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

功能

• 云操作引导 — 为 Agent 提供 20 多种常用 Huawei Cloud 服务（ECS、OBS、VPC、RDS、GaussDB、FunctionGraph、APIG、CCE 等）的分步指导
• 安全优先的执行 — 所有写操作都需要用户明确批准；输出中的凭据和机密会自动脱敏
• 执行前风险检查 — 在执行前识别公开暴露、凭据泄露和破坏性操作
• 区域感知 — 自动发现可用区域，并在创建资源前检查服务是否可用
• 沙箱（DevStation） — 用于部署 Web 应用的临时云运行时，可即时预览公开 URL

支持的服务

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

以上是预先配置的指导列表；其余 200 多种 Huawei Cloud 服务仍可通过 KooCLI / API / SDK 路由访问（参见 capability-discovery 和 cli-and-auth 元技能）。

文档

• 架构
• 安全模型
• 钩子规则模型
• DeepSeek Harness 集成
• 更新日志
• KooCLI 官方文档

贡献者

许可证

本项目采用 Apache-2.0 许可证。请参阅 LICENSE。