Ecovacs Deebot control#

What you need#

InputNotes**AK (Access Key)**Create or view it in the Ecovacs Open Platform “Service overview” ( China: https://open.ecovacs.cn/, Global: https://open.ecovacs.com/), then copy it into env vars, a config file, or chat yourself. Pick the portal region that matches your account. Do not hand account passwords to automation; this skill does not log in on your behalf.Gateway base URL (optional)Defaults to the same host as the Open Platform ( China https://open.ecovacs.cn, Global https://open.ecovacs.com). Override with ECOVACS_PORTAL_URL for a self-hosted or local gateway (e.g. mcp_portal_services).Device nickname fragmentUsed to pick one robot. Take a substring of nick or name from the device list (fuzzy match).

If the AK is invalid (e.g. errno 3000), refresh it on the Open Platform—do not try to replace user login with other APIs.

---

Three steps#

1. Configure AK → 2. Device list → 3. Send commands

1. Configure AK (pick one)#

bash

export ECOVACS_AK="YOUR_AK"
# or: python3 scripts/ecovacs.py set-ak <ak>
# writes ~/.ecovacs_session.json with {"ak":"..."} only

2. Device list#

bash

python3 scripts/ecovacs.py devices

Note the nick / name fragment you will use as <nick> below.

3. Common CLI operations#

Let SCRIPT=scripts/ecovacs.py.

Queries

• Battery: python3 "$SCRIPT" battery <nick>
• Work state (clean / charge / station): python3 "$SCRIPT" status <nick>

Cleaning

• Whole-home auto clean: python3 "$SCRIPT" clean <nick> start
• Pause / resume / stop: python3 "$SCRIPT" clean <nick> pause or resume / stop

Charging

• Go charge / stop go-charge: python3 "$SCRIPT" charge <nick> go or stop

---

HTTP gateway (no Python)#

BASE_URL is the same as ECOVACS_PORTAL_URL (defaults to the regional Open Platform host).

Device list

bash

curl -sS "${BASE_URL}/robot/skill/deviceList?ak=YOUR_AK"

Control: POST /robot/skill/ctl with JSON ak, optional nickName (fuzzy match on list), and ctl.cmd / ctl.data.

bash

curl -sS -X POST "${BASE_URL}/robot/skill/ctl" -H 'Content-Type: application/json' \
  -d "{\"ak\":\"${AK}\",\"nickName\":\"nick-fragment\",\"ctl\":{\"cmd\":\"Charge\",\"data\":{\"act\":\"go\"}}}"

CloudCtl expects Charge, Clean, etc. with official casing— not lowercase charge.

More JSON examples (e.g. zone clean) are in references/api.md.

---

Errors and enums (troubleshooting)#

Responses are usually two layers: outer msg / code; inner cloudctl payload under nested ctl.data with ret ( ok/ fail), errno, optional error.

SituationMeaning / next stepAppendix F 5009Command or parameter combo not supported on this model (casing, firmware); verify model, try GetWorkState / GetBatteryInfo namingAppendix F 10004Offline / timeout / powered off / re-provisionedAppendix F 10000Low battery, cannot runAppendix F 10005Host fault (lifted, dustbin missing, …)Clean 10006 / Charge 10006Internal host fault (appendix C/D)Appendix F 4000Malformed JSONAppendix F 4504Token check failed—verify AKret=failRead errno and error together

Water level: In sweep-only mode (no mopping / tank inactive), SetWaterInfo often fails ( ret=fail); switch to a mopping-capable mode first.

Clean enums: act = s/ p/ r/ h; workMode 0–3; zone clean uses type=spotarea + aid from GetAreaList mssid. Charge: go / stopGo.

Full tables: see “CloudCtl errors and enums” at the end of references/api.md.

---

How to read the docs#

FileAudienceContentsThis SKILL.mdEnd usersInputs, three steps, CLI, HTTPreferences/api.mdIntegratorsPaths, bodies, enums, curlreferences/agent-internal.mdInternalSmart clean, rooms, polling, GetWorkState heuristics

Prefer this page for user-facing guidance; use references/agent-internal.md only when you need implementation-level troubleshooting.