🤖 VectorClaw

---

Architecture

┌─────────────┐    stdio MCP    ┌──────────────────┐    gRPC/WiFi    ┌─────────┐
│  AI Agent   │ ─────────────── │  vectorclaw-mcp  │ ─────────────── │  Vector │
│  (OpenClaw) │                 │  (Python 3.11+)  │                 │  Robot  │
└─────────────┘                 └──────────────────┘                 └─────────┘

All communication is local-only — no cloud dependency at runtime (Wire-Pod setup path).

See Security Architecture for the full trust model.

---

Table of Contents

• Architecture
• Current Status
• Quickstart
• MCP Client Configuration
• Available Tools
• Contributing
• Docs Map

---

Current Status

v1.0.0 Released · 2026-03-01

16 tools verified ✅ on hardware | 7 tools experimental ⚠️

Known limitations:

• vector_drive_on_charger — requires the charger to be in Vector’s recently-observed world model; call vector_scan first to give Vector a chance to locate the charger before attempting to dock (observed: invoking while charger is unobserved causes the command to time out without any robot motion)
• Perception tools (vector_find_faces, vector_list_visible_faces, vector_face_detection, vector_list_visible_objects) — return empty results when vision modes are not active; vision modes are enabled automatically at connect but will be disabled for the remainder of the session after a vector_vision_reset call (reconnect to restore)
• Idle behaviors — Vector’s autonomous animations can overlap with commanded behaviors; use one-command-at-a-time sequencing and wait for completion before issuing the next command

See ROADMAP.md for the full milestone plan.

---

Quickstart

Requirements: Python 3.11+ · Wire-Pod running · Vector on local WiFi

For the complete walkthrough (Wire-Pod install, robot auth, WiFi config, troubleshooting) see docs/SETUP.md.

Guided Setup (recommended for new users)

The vectorclaw-setup wizard handles configuration, SDK validation, connectivity check, and a smoke test in one go:

pip install vectorclaw-mcp
vectorclaw-setup

You will be prompted for your robot’s serial number and optional IP address. On success you’ll see a clear SETUP PASSED message and the next-steps command. On failure every step includes an exact remediation hint.

See docs/OPENCLAW_SETUP_SKILL.md for full details.

---

Manual Setup

Step 1 — Install VectorClaw

pip install vectorclaw-mcp

Step 2 — Configure Vector SDK

Wire-Pod is the canonical self-hosted server for Vector. Install the SDK distribution and run the one-time auth wizard:

pip install wirepod_vector_sdk
python -m anki_vector.configure

Note: wirepod_vector_sdk installs under the anki_vector Python namespace, so all imports and CLI commands use anki_vector.

Step 3 — Set environment variables

export VECTOR_SERIAL="your-robot-serial"   # required — printed on underside of robot
export VECTOR_HOST="192.168.x.x"           # optional — auto-discovered if omitted
export VECTOR_REPEAT_GUARD_SECONDS="10"    # optional — refuse identical actuating calls within N s (0 = off)

Step 4 — Run the server

vectorclaw-mcp
# or
python -m vectorclaw_mcp

---

MCP Client Configuration

Add the following block to your mcporter.json (or equivalent MCP client config).

With uvx (recommended — no prior install needed)

{
  "mcpServers": {
    "vectorclaw": {
      "command": "uvx",
      "args": ["vectorclaw-mcp"],
      "env": {
        "VECTOR_SERIAL": "your-serial-here"
      }
    }
  }
}

With pip install (if installed locally)

{
  "mcpServers": {
    "vectorclaw": {
      "command": "vectorclaw-mcp",
      "env": {
        "VECTOR_SERIAL": "your-serial-here"
      }
    }
  }
}

---

Available Tools

Status legend: ✅ Verified on hardware | ⚠️ Experimental (requires specific preconditions; see API Reference)

⚠️ Charger prerequisite: vector_drive requires the robot to be off the charger. Call vector_drive_off_charger first, or set VECTOR_AUTO_DRIVE_OFF_CHARGER=1 for automatic undocking.

See docs/MCP_API_REFERENCE.md for full parameter details and response schemas.

---

Contributing

1. 🌿 Branch: branch off dev, use / naming (e.g. fix/vector-face-payload, feat/vector-scan)
2. 🧪 Tests: add or update tests under tests/; all tests use the mocked SDK — no hardware required
3. ✅ CI: Python 3.11 is required and must pass; Python 3.12 is experimental/informational — run pytest tests/ -v locally before opening a PR
4. 🤖 Hardware: if your change touches a tool or connection layer, record a smoke-test run in Hardware Smoke Log following the Hardware Test Playbook
5. 🎯 PR scope: keep PRs focused — separate docs, feature, and refactor changes to reduce merge-conflict risk with parallel lanes

---

Docs Map

🛠️ Setup & Runtime

📡 API & SDK

🔬 Hardware Validation

🔒 Security

---

License

MIT — see LICENSE.