功能描述

Control JoyIn AI robots (W-1 Walle / M-1 Mini) — movement, follow, photo, video, live stream, TTS, agent config, and device status via OpenAPI.

使用说明 (SKILL.md)

JoyIn Robot Control

Name: JoyIn Robot Control
Author: yanfang724

Control JoyIn AI robots through the official OpenAPI. Supports W-1 (Walle) and M-1 (Mini) robots.

Setup

OpenClaw Configuration

Add the following to ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "joyin-robot-control": {
        "enabled": true,
        "apiKey": "YOUR_AUTH_KEY",
        "env": {
          "JOYIN_API_BASE": "https://api-open-test.joyin-ai.com",
          "JOYIN_AUTH_KEY": "YOUR_AUTH_KEY",
          "JOYIN_DEVICE_SN": "YOUR_DEVICE_SN",
          "JOYIN_DEVICE_TYPE_ID": "3"
        }
      }
    }
  }
}

See {baseDir}/openclaw.config.example.json5 for a full template.

Environment Variables

Variable	Required	Description
`JOYIN_API_BASE`	Yes	API base URL (test: `https://api-open-test.joyin-ai.com`)
`JOYIN_AUTH_KEY`	Yes	Authorization key (contact JoyIn staff to obtain)
`JOYIN_DEVICE_SN`	Yes	Target device serial number
`JOYIN_DEVICE_TYPE_ID`	No	`3` for Walle (default), `2` for Mini

OpenClaw injects these via skills.entries.*.env at agent run time. They are scoped to the run and do not leak into the global shell environment.

Tool

python3 {baseDir}/scripts/robot_cmd.py \x3Ccommand> [options]

Agent Workflow Rules (IMPORTANT)

ALWAYS run preflight before sending any robot command. This checks whether the device is online, its battery level, and current work mode.

Decision flow:

1. Run: python3 {baseDir}/scripts/robot_cmd.py preflight
2. Check the result:
   - "ready": false  → Tell the user why (offline / OTA / low battery). Do NOT send commands.
   - "ready": true, with "note" about current mode → Inform the user, then proceed.
   - "ready": true, idle → Proceed with the command.
3. Execute the requested command.
4. Report the result to the user.

State-aware behavior:

current_status	Meaning	What to do
`offline`	Device not connected	Tell user. Do not send commands.
`idle`	Ready	Proceed normally.
`follow`	Following a person	Warn before sending conflicting commands (e.g. remote_control). Use `stop` first.
`remote_control`	Joystick active	Already in RC mode. Can send move commands directly.
`patrol`	Patrolling	Warn before interrupting. Use `stop` first.
`go_charge`	Returning to charger	Warn before interrupting.
`guard`	Monitoring	Warn before interrupting.
`ota`	Firmware updating	Do NOT send any commands. Wait.
`build_map`	Building SLAM map	Do NOT interrupt.
`active_action`	Performing action	Conflicts with follow. Use `stop` first if needed.

Battery rules:

\x3C 10% and not charging → Suggest charge command before any movement.
\x3C 5% → Refuse movement commands, only allow charge and status.

Quick Examples

# ALWAYS run preflight check first
python3 {baseDir}/scripts/robot_cmd.py preflight

# Move robot forward
python3 {baseDir}/scripts/robot_cmd.py move --direction forward

# Stop all movement
python3 {baseDir}/scripts/robot_cmd.py stop

# Make robot say something
python3 {baseDir}/scripts/robot_cmd.py tts --text "你好，我是你的机器人助手"

# Check device status (battery, online, charging)
python3 {baseDir}/scripts/robot_cmd.py status

# Get live video stream URL
python3 {baseDir}/scripts/robot_cmd.py live_pull_url

Command Reference

1. Movement — Remote Control

Enter / Exit remote control mode:

python3 {baseDir}/scripts/robot_cmd.py rc_enter
python3 {baseDir}/scripts/robot_cmd.py rc_exit

Chassis movement (8 directions, send continuously at ~100ms interval, robot stops when commands stop):

python3 {baseDir}/scripts/robot_cmd.py move --direction forward
python3 {baseDir}/scripts/robot_cmd.py move --direction backward
python3 {baseDir}/scripts/robot_cmd.py move --direction left
python3 {baseDir}/scripts/robot_cmd.py move --direction right
python3 {baseDir}/scripts/robot_cmd.py move --direction left_up
python3 {baseDir}/scripts/robot_cmd.py move --direction right_up
python3 {baseDir}/scripts/robot_cmd.py move --direction left_down
python3 {baseDir}/scripts/robot_cmd.py move --direction right_down

# Stop chassis movement
python3 {baseDir}/scripts/robot_cmd.py move_stop

Head control (Walle only) — up/down/left/right, send continuously at ~100ms:

python3 {baseDir}/scripts/robot_cmd.py head --direction up
python3 {baseDir}/scripts/robot_cmd.py head --direction down
python3 {baseDir}/scripts/robot_cmd.py head --direction left
python3 {baseDir}/scripts/robot_cmd.py head --direction right
python3 {baseDir}/scripts/robot_cmd.py head --direction stop

Arm control (Walle only) — left_arm or right_arm:

python3 {baseDir}/scripts/robot_cmd.py arm --side left --direction up
python3 {baseDir}/scripts/robot_cmd.py arm --side left --direction down
python3 {baseDir}/scripts/robot_cmd.py arm --side left --direction stop
python3 {baseDir}/scripts/robot_cmd.py arm --side right --direction up
python3 {baseDir}/scripts/robot_cmd.py arm --side right --direction stop

Reset position (Walle only):

python3 {baseDir}/scripts/robot_cmd.py reset --target all     # reset all
python3 {baseDir}/scripts/robot_cmd.py reset --target head    # reset head only
python3 {baseDir}/scripts/robot_cmd.py reset --target arm     # reset arms only

2. Fixed Actions (Mini only)

python3 {baseDir}/scripts/robot_cmd.py car_on          # 上车
python3 {baseDir}/scripts/robot_cmd.py car_off         # 下车
python3 {baseDir}/scripts/robot_cmd.py standup          # 站立
python3 {baseDir}/scripts/robot_cmd.py boot_off         # 收脚
python3 {baseDir}/scripts/robot_cmd.py boot_on          # 卡脚
python3 {baseDir}/scripts/robot_cmd.py hello            # 打招呼
python3 {baseDir}/scripts/robot_cmd.py hello_off        # 收手
python3 {baseDir}/scripts/robot_cmd.py head_up          # 抬头
python3 {baseDir}/scripts/robot_cmd.py head_down        # 回头 (低头)
python3 {baseDir}/scripts/robot_cmd.py charge           # 回充电桩
python3 {baseDir}/scripts/robot_cmd.py charge_stop      # 停止回充

3. Emergency Stop

python3 {baseDir}/scripts/robot_cmd.py stop             # 急停，停止所有移动和功能

4. Voice — TTS

# Play text on device speaker
python3 {baseDir}/scripts/robot_cmd.py tts --text "你好世界"

# Play text then close microphone (keep_silent=1)
python3 {baseDir}/scripts/robot_cmd.py tts --text "请安静" --keep-silent

5. Device Status & Preflight

# Pre-flight check (ALWAYS run this before any command)
python3 {baseDir}/scripts/robot_cmd.py preflight
# Returns: ready (bool), current_status, battery, is_charging, issues[], suggestion

# Get raw device status
python3 {baseDir}/scripts/robot_cmd.py status

Preflight response example (ready):

{
  "ready": true,
  "current_status": "idle",
  "current_status_name": "空闲",
  "battery": 85,
  "is_charging": false,
  "note": "Device is online and idle. Ready to accept commands."
}

Preflight response example (not ready):

{
  "ready": false,
  "current_status": "offline",
  "battery": -1,
  "issues": ["Device is OFFLINE — cannot accept commands"],
  "suggestion": "Device is OFFLINE — cannot accept commands"
}

6. Live Video

# Start push stream from device camera
python3 {baseDir}/scripts/robot_cmd.py live_push --status 1

# Stop push stream
python3 {baseDir}/scripts/robot_cmd.py live_push --status 0

# Get pull stream URL (HLS/RTMP)
python3 {baseDir}/scripts/robot_cmd.py live_pull_url

# Get push URL
python3 {baseDir}/scripts/robot_cmd.py live_push_url

7. ASR Result

# Get the robot's latest speech recognition result
python3 {baseDir}/scripts/robot_cmd.py asr_result

8. WiFi Configuration

# Configure robot WiFi (base64-encoded SSID and password)
python3 {baseDir}/scripts/robot_cmd.py wifi --ssid "MyWiFi" --password "12345678"

9. LLM Configuration (register your own model)

# Register a custom LLM
python3 {baseDir}/scripts/robot_cmd.py llm_register --name "My GPT" --base-url "https://api.openai.com/v1" --api-key "sk-xxx" --model "gpt-4"

# List registered LLMs
python3 {baseDir}/scripts/robot_cmd.py llm_list

# Update a registered LLM
python3 {baseDir}/scripts/robot_cmd.py llm_update --id 123 --model "gpt-4o"

10. Agent Configuration

# Create an agent with a registered LLM
python3 {baseDir}/scripts/robot_cmd.py agent_create --name "My Agent" --llm-id 123

# List agents
python3 {baseDir}/scripts/robot_cmd.py agent_list

# Update agent
python3 {baseDir}/scripts/robot_cmd.py agent_update --id 123 --name "New Name"

# Bind agent to a device
python3 {baseDir}/scripts/robot_cmd.py agent_bind --agent-id 123

# Query device's bound agent
python3 {baseDir}/scripts/robot_cmd.py agent_query

# Reset device to default JoyIn agent
python3 {baseDir}/scripts/robot_cmd.py agent_reset

Device Types

Type ID	Model	Codename	Key Capabilities
3	W-1 (Walle)	walle	Chassis + head + arm control, 8-direction joystick, position reset
2	M-1 (Mini)	mini	Chassis control, fixed body actions (standup/car/hello/head), charging

API Protocol

Base URL: https://api-open-test.joyin-ai.com (test)
Auth: All requests carry 3 headers — Authorization, Device-Sn, Device-Type-Id
Robot commands: POST /v1/device/interaction/cmd with body {"cmd_type":"...","status":"...","name":"...","data":{...}}
Response format: {"code": 200, "msg": "success", "data": {...}}

Important Notes

The device must be online for commands to work.
Joystick commands (move/head/arm) need to be sent continuously at ~100ms intervals. The robot stops automatically when commands stop arriving.
keep_silent=1 on TTS means the microphone will be closed after playback.
Some APIs (LLM config, Agent config) are marked as "开发中" and may not be fully available.

安全使用建议

This skill appears coherent with its stated purpose, but before installing: 1) verify JOYIN_API_BASE points to the official JoyIn API (avoid test/personal hosts unless you intend to use them); 2) keep JOYIN_AUTH_KEY private — prefer injecting it from a secure env/provider rather than storing plaintext in openclaw.json; 3) consider using a scoped/limited token for robot control and rotate it if possible; 4) test first with a non-production/test device to confirm behavior (and always run the provided preflight check before issuing movement commands); and 5) be aware the agent can invoke this skill autonomously (platform default), so restrict access to the skill only to trusted agents/users if physical safety is a concern.

功能分析

Type: OpenClaw Skill Name: joyin-robot-control Version: 1.1.0 The skill bundle provides a legitimate interface for controlling JoyIn AI robots (W-1 and M-1) via their official OpenAPI. The Python script (scripts/robot_cmd.py) is a clean implementation using only the standard library to perform HTTP requests for movement, status, and configuration. The instructions in SKILL.md are focused on operational safety, such as requiring 'preflight' checks for battery levels and device status. While the skill handles sensitive data like WiFi credentials and LLM API keys, these actions are aligned with the stated purpose of device and agent configuration, with no evidence of exfiltration or unauthorized access.

能力评估

✓ Purpose & Capability

Name/description match the contents: a Python CLI that calls a JoyIn OpenAPI. Required binary (python3) and environment variables (API base, auth key, device SN) are sensible and necessary for the described robot control functionality.

✓ Instruction Scope

SKILL.md instructs the agent to run the included Python script and to perform a preflight check before commands. The instructions reference only the declared env vars and the included example config; they do not request unrelated files, system secrets, or transmission to unexpected endpoints.

✓ Install Mechanism

No install spec or external downloads; the skill is instruction-only with a bundled Python script that uses only the standard library. Nothing is fetched from arbitrary URLs or written to system locations during install.

✓ Credentials

The skill requests a single service credential (JOYIN_AUTH_KEY) plus API base and device identifiers — all directly relevant to calling the robot API. The number and naming of env vars are proportional to the functionality.

✓ Persistence & Privilege

The skill does not request always:true and does not modify other skills or global agent settings. disable-model-invocation is false (normal), which allows autonomous invocation but is not combined with suspicious access patterns.

版本历史

v1.1.0

Add preflight check command and state-aware agent workflow rules.

v1.0.0

Initial release: 35 commands for W-1 Walle and M-1 Mini robots.

元数据

Slug joyin-robot-control

版本 1.1.0

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 2

常见问题