RosClaw Autonomy

Companion OpenClaw plugin that adds embodied autonomy behaviors on top of the base RosClaw plugin.

This package is not a replacement for rosclaw. The base rosclaw plugin still owns the direct ROS 2 interface surface (ros2_* tools, transport switching, emergency stop command, capability discovery). rosclaw-autonomy adds:

• high-level rosclaw_* autonomy tools
• autonomy-mode aware prompt context
• safety policy that constrains raw motion tools from the base plugin
• optional background autonomy turns when the OpenClaw runtime supports them
• structured autonomy audit logging

Install both plugins together.

Split Model

Base rosclaw plugin

Use the base plugin for:

• raw ROS 2 tools such as ros2_publish, ros2_service_call, ros2_action_goal, and ros2_subscribe_once
• transport management
• capability discovery
• direct commands like /estop

rosclaw-autonomy plugin

Use this plugin for:

• autonomy mode changes
• roaming and exploration requests
• return-home and hold-position behaviors
• robot belief injection into the agent prompt
• policy that prefers high-level autonomy over direct /cmd_vel control

The intended setup is:

1. Install rosclaw
2. Install rosclaw-autonomy
3. Configure both against the same robot / namespace
4. Let the base plugin expose raw ROS interfaces while the autonomy plugin steers the agent toward embodied, higher-level behavior

Robot-Side Requirements

The autonomy plugin expects the robot to expose the RosClaw autonomy interfaces. These are typically provided by the rosclaw_autonomy ROS 2 package in the robot stack.

Expected interfaces:

• Topic: /rosclaw/autonomy_mode (rosclaw_autonomy_msgs/msg/AutonomyMode)
• Topic: /rosclaw/robot_belief (rosclaw_autonomy_msgs/msg/RobotBelief)
• Topic: /rosclaw/current_intent (std_msgs/msg/String)
• Service: /rosclaw/set_autonomy_mode (rosclaw_autonomy_msgs/srv/SetAutonomyMode)
• Service: /rosclaw/return_home (rosclaw_autonomy_msgs/srv/ReturnHome)
• Action: /rosclaw/roam (rosclaw_autonomy_msgs/action/Roam)

Optional but useful:

• Topic: /rosclaw/safety_status for robot-reported velocity limits
• Topic: /rosclaw/scene for perception summaries injected into the prompt

If these autonomy interfaces are missing, the plugin can still load, but high-level autonomy tools will fail or operate with degraded context.

Installation

Install the base plugin first:

openclaw plugins install @openclaw/rosclaw

Then install the autonomy companion plugin:

openclaw plugins install @openclaw/rosclaw-autonomy

If you are developing locally:

npm install
npm run build

This package is designed to be used alongside the base @openclaw/rosclaw plugin, not instead of it.

Configuration

The autonomy plugin uses the same transport and robot targeting concepts as the base plugin, plus an autonomy block.

{
  "transport": {
    "mode": "rosbridge"
  },
  "rosbridge": {
    "url": "ws://localhost:9090",
    "reconnect": true,
    "reconnectInterval": 3000
  },
  "robot": {
    "name": "Robot",
    "namespace": ""
  },
  "safety": {
    "maxLinearVelocity": 1.0,
    "maxAngularVelocity": 1.5,
    "allowlistedTopics": [],
    "allowlistedServices": [],
    "allowlistedActions": [],
    "workspaceLimits": {
      "xMin": -10,
      "xMax": 10,
      "yMin": -10,
      "yMax": 10
    }
  },
  "autonomy": {
    "enabled": true,
    "startupMode": "FULL_AUTONOMY",
    "tickHz": 1,
    "idleRoamStrategy": "frontier",
    "defaultExecutor": "auto",
    "manualReturnDelaySec": 5,
    "lowBatteryPct": 20,
    "stuckTimeoutSec": 15,
    "maxToolCallsPerMinute": 30
  }
}

Configuration reference

Key	Default	Description
transport.mode	"rosbridge"	Transport mode for autonomy subscriptions and autonomy tool execution.
rosbridge.url	"ws://localhost:9090"	Rosbridge WebSocket URL.
rosbridge.reconnect	true	Auto-reconnect autonomy transport on disconnect.
rosbridge.reconnectInterval	3000	Reconnect interval in milliseconds.
local.domainId	0	ROS 2 domain ID for local DDS mode.
robot.name	"Robot"	Display name used in logs and fallback prompt context.
robot.namespace	""	Namespace used to resolve /rosclaw/* autonomy interfaces.
safety.maxLinearVelocity	1.0	Fallback max linear speed used by autonomy policy.
safety.maxAngularVelocity	1.5	Fallback max angular speed used by autonomy policy.
safety.allowlistedTopics	[]	Raw ROS topics the autonomy policy may allow through.
safety.allowlistedServices	[]	Raw ROS services the autonomy policy may allow through.
safety.allowlistedActions	[]	Raw ROS actions the autonomy policy may allow through.
safety.workspaceLimits	{-10..10}	Navigation goal bounds enforced by the autonomy validator.
autonomy.enabled	true	Enables the autonomy runtime service and autonomy hooks.
autonomy.startupMode	"FULL_AUTONOMY"	Seed mode used until live robot mode is observed.
autonomy.tickHz	1	Background autonomy tick frequency.
autonomy.idleRoamStrategy	"frontier"	Default roam strategy for rosclaw_start_roam.
autonomy.defaultExecutor	"auto"	Preferred roam executor: auto, nav2, or cmd_vel.
autonomy.manualReturnDelaySec	5	Delay before autonomy should resume after manual intervention.
autonomy.lowBatteryPct	20	Threshold for low-battery autonomy logic on the robot side.
autonomy.stuckTimeoutSec	15	Timeout for stuck-motion detection on the robot side.
autonomy.maxToolCallsPerMinute	30	Rate limit applied per tool by the autonomy validator.

What the Plugin Provides

AI tools

Tool	Description
rosclaw_set_mode	Set the robot autonomy mode via /rosclaw/set_autonomy_mode
rosclaw_start_roam	Start a robot-side roam / explore behavior
rosclaw_stop_and_hold	Stop roaming and move into supervised hold
rosclaw_return_home	Ask the robot autonomy manager to return home
rosclaw_get_belief	Return the latest autonomy / belief snapshot cached by the plugin

Hooks

• before_prompt_build

  • fetches the capability manifest through the plugin transport
  • reads autonomy state from /rosclaw/autonomy_mode, /rosclaw/robot_belief, and /rosclaw/current_intent
  • optionally reads /rosclaw/scene
  • injects an autonomy overlay into the system prompt that explicitly tells the agent to use rosclaw_* tools first and treat raw ros2_* driving as an exception

• before_tool_call

  • rate limits autonomy-sensitive tool usage
  • blocks direct /cmd_vel publishes in autonomous modes
  • blocks unsafe navigation goals outside the configured workspace
  • blocks protected control-plane parameter and service changes
  • prevents conflicting motion commands while a roam behavior is already active

Managed services

• rosclaw-autonomy-transport

  • maintains a ROS transport for autonomy tool execution and subscriptions

• rosclaw-autonomy

  • seeds autonomy mode state
  • subscribes to robot autonomy topics
  • optionally asks the OpenClaw runtime for low-rate autonomous background turns when runtime.agent.enqueueAutonomousTurn(...) is available

Prompting Behavior

The autonomy plugin does not try to replace the base plugin's capability dump. Instead, it adds an autonomy-specific overlay that tells the agent:

• the current autonomy mode
• the current intent
• current robot belief such as pose, nav state, obstacle distance, battery, and active executor
• which autonomy interfaces are actually present on the robot
• that rosclaw_* tools should be preferred for exploration and free-roaming
• that raw ros2_* tools from the base plugin are still available for recovery, inspection, or clearly manual tasks

This is the core of the split: the base plugin exposes raw affordances, and the autonomy plugin shapes how the agent uses them.

Safety Model

This plugin enforces autonomy policy in front of both:

• its own rosclaw_* tools
• the raw ros2_* tools exposed by the base plugin

Key rules:

• direct ros2_publish to /cmd_vel is blocked unless the robot is in MANUAL or ASSISTED
• navigation goals outside workspaceLimits are blocked
• raw parameter service calls and protected RosClaw node parameter writes are blocked
• if a roam action is active, a second motion action is blocked until the agent stops and holds first

This means the autonomy plugin can be installed as a policy overlay without duplicating the base ROS interface surface.

Development

Run the local checks:

npm run typecheck
npm test

The current autonomy-focused tests cover:

• package identity and split behavior
• autonomy-only tool registration
• direct-drive blocking in autonomous modes
• roam request validation
• autonomy overlay prompt generation
• manifest caching and transport lifecycle handling

License

Apache-2.0