Govee OpenAPI（无脚本）

仅使用手动 curl 命令控制 Govee 设备。

Linux 系统要求

• - 支持 bash 的 Linux shell。
• 已安装 curl。
• 可访问 https://developer-api.govee.com 和 https://developer.govee.com。
• 已关联支持设备的 Govee 账户。
• 可选：jq 用于美化 JSON 响应输出。

快速检查：

bash
bash --version | head -n 1
curl --version | head -n 1
command -v jq >/dev/null && jq --version || echo jq 未安装（可选）

所需凭证

• - GOVEEAPIKEY（必需）

自主使用限制

• - 仅从您选择的用户级密钥文件中读取 GOVEEAPIKEY。
• 不读取无关的密钥文件或系统凭证。
• 限制出站请求仅访问：

• - 在控制多个设备或执行批量更改前需征得确认。

获取 Govee API 密钥

1. 1. 打开 https://developer.govee.com/。
2. 使用拥有设备的同一 Govee 账户登录。
3. 进入开发者控制台的 API 密钥部分。
4. 生成/申请密钥并复制。
5. 妥善保管（像对待密码一样对待它）。

如果门户界面发生变化，请遵循相同流程：登录 Govee 开发者平台 → 找到 API 密钥管理 → 创建密钥。

安全本地存储（按用户）

切勿将 API 密钥存储在技能文件、Git 或聊天记录中。

创建用户级密钥文件（除非有意以 root 身份运行，否则避免使用 /root）：

bash
mkdir -p $HOME/.openclaw/secrets
cat > $HOME/.openclaw/secrets/govee.env < export GOVEEAPIKEY=<你的API密钥>
EOF
chmod 600 $HOME/.openclaw/secrets/govee.env

仅将此变量加载到当前 shell（不使用 set -a）：

bash
source $HOME/.openclaw/secrets/govee.env

API 基础 URL

bash
https://developer-api.govee.com/v1

首先发现设备

在控制灯光前，列出设备并复制您自己的 device 和 model：

bash
curl -sS -X GET https://developer-api.govee.com/v1/devices \
-H Govee-API-Key: $GOVEEAPIKEY \
-H Content-Type: application/json

查看设备状态

bash
curl -sS -X GET https://developer-api.govee.com/v1/devices/state?device=<设备>&model=<型号> \
-H Govee-API-Key: $GOVEEAPIKEY \
-H Content-Type: application/json

控制命令

开启

bash
curl -sS -X PUT https://developer-api.govee.com/v1/devices/control \
-H Govee-API-Key: $GOVEEAPIKEY \
-H Content-Type: application/json \
-d {device:<设备>,model:<型号>,cmd:{name:turn,value:on}}

关闭

bash
curl -sS -X PUT https://developer-api.govee.com/v1/devices/control \
-H Govee-API-Key: $GOVEEAPIKEY \
-H Content-Type: application/json \
-d {device:<设备>,model:<型号>,cmd:{name:turn,value:off}}

亮度（1-100）

bash
curl -sS -X PUT https://developer-api.govee.com/v1/devices/control \
-H Govee-API-Key: $GOVEEAPIKEY \
-H Content-Type: application/json \
-d {device:<设备>,model:<型号>,cmd:{name:brightness,value:75}}

RGB 颜色

bash
curl -sS -X PUT https://developer-api.govee.com/v1/devices/control \
-H Govee-API-Key: $GOVEEAPIKEY \
-H Content-Type: application/json \
-d {device:<设备>,model:<型号>,cmd:{name:color,value:{r:120,g:180,b:255}}}

响应检查

成功通常返回：

json
{code:200,message:Success}

如果 code 不是 200，则视为失败。

故障排除

• - 401 / 未授权：密钥缺失、过期或无效。
• 429 / 速率限制：减慢重试频率。
• 命令被拒绝：型号不支持该命令（查看 supportCmds）。
• 设备列表为空：账户没有关联的支持设备。

安全规则

• - 文档中仅使用占位符（<设备>、<型号>、<你的API密钥>）。
• 不要在发布的制品中包含真实密钥或设备 ID。
• 优先逐设备操作，避免批量更改。
• 避免将 API 密钥粘贴到聊天中。