OpenClaw Databricks Plugin

External OpenClaw plugin for conservative Databricks SQL access.

Requirements:

• OpenClaw host version >= 2026.4.2
• Plugin entry key: plugins.entries.databricks

This package provides:

• Runtime tool: databricks_sql_readonly
• Skill pack: databricks
• Read-only SQL execution only (SELECT or WITH ... SELECT)

Why this plugin

This plugin is built for secure, production-minded Databricks usage inside OpenClaw.

Key differentiators:

• Real OpenClaw code plugin, not only an instruction pack
• Conservative read-only SQL scope
• Explicit compatibility metadata for OpenClaw plugin packaging
• Fail-closed validation model
• Reduced attack surface compared with broad operational connector patterns
• Clear separation between supported execution paths and unsupported requests

Security posture

This plugin intentionally limits scope to safer Databricks workflows:

• Supports single SELECT
• Supports single WITH ... SELECT
• Blocks mutating SQL operations
• Blocks multi-statement execution
• Supports optional catalog/schema allowlists
• Rejects ambiguous target resolution when allowlists are enforced

This design is intentional. The goal is not maximum surface area. The goal is safer, more predictable Databricks access for OpenClaw deployments.

Who this is for

Use this plugin if you want:

• safer Databricks SQL access in OpenClaw
• a real plugin artifact instead of only textual instructions
• controlled enterprise usage patterns
• reduced operational risk
• compatibility-aware plugin packaging

Install

Preferred:

openclaw plugins install @kansodata/openclaw-databricks-plugin

Source-specific:

openclaw plugins install clawhub:@kansodata/openclaw-databricks-plugin
openclaw plugins install npm:@kansodata/openclaw-databricks-plugin

OpenClaw checks ClawHub first for bare package installs, then falls back to npm.

Configure

{
  "plugins": {
    "entries": {
      "databricks": {
        "enabled": true,
        "config": {
          "host": "https://dbc-example.cloud.databricks.com",
          "token": "dapi...",
          "warehouseId": "abc123",
          "readOnly": true
        }
      }
    }
  }
}

Restart gateway after configuration changes.

For real execution, host, token, and warehouseId are required.

Configuration Fields

Required:

• host
• token
• warehouseId

Optional:

• timeoutMs (default 30000)
• retryCount (default 1, range 0..3)
• pollingIntervalMs (default 1000)
• maxPollingWaitMs (default 30000)
• allowedCatalogs (default [])
• allowedSchemas (default [])
• readOnly (must stay true)

Environment fallbacks:

• DATABRICKS_HOST
• DATABRICKS_TOKEN
• DATABRICKS_WAREHOUSE_ID
• DATABRICKS_READ_ONLY

Security and Hardening

• Fail-closed host validation:
  • HTTPS only
  • No path/query/fragment/userinfo/custom port
  • No localhost/IP literals
  • Hostname must match Databricks suffixes (*.cloud.databricks.com, *.azuredatabricks.net, *.gcp.databricks.com)
• Token and sensitive values are redacted in runtime logs and normalized error output.
• SQL policy is read-only and blocks mutating keywords and multi-statement input.
• Allowlists are enforced conservatively:
  • If targets cannot be resolved safely, request is rejected.
  • Ambiguous target syntax is rejected when allowlists are configured.
  • catalog and schema request parameters do not bypass SQL target checks.

Runtime Behavior

databricks_sql_readonly:

• Submits SQL via Databricks SQL Statements API.
• Polls statement status until a terminal state or timeout budget exhaustion.
• Treats SUCCEEDED as success.
• Treats FAILED / CANCELED as explicit failures.
• Uses retryCount for transient submit and poll failures (429, 408, 5xx, and timeout aborts).

Scope Limits

Out of scope in this version:

• Jobs API execution
• Unity Catalog lineage APIs
• Any mutating SQL support

Publish Notes

This package is intended for external distribution (ClawHub/npm), not bundled OpenClaw core.

External Publish Workflow

1. Validate locally:

pnpm install
pnpm lint
pnpm typecheck
pnpm test
npm pack --dry-run

2. Publish to npm (when credentials are configured):

npm publish --access public

3. Publish/list in ClawHub according to the ClawHub submission flow for external plugins.