Skip to content

Commit 175ebc4

Browse files
antonslutskymsantonslutskyms
committed
adding azure blob storage extension
1 parent 3496ecc commit 175ebc4

File tree

9 files changed

+925
-0
lines changed

9 files changed

+925
-0
lines changed

‎extensions/azure-blob/README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Azure Blob Storage plugin
2+
3+
OpenClaw plugin that exposes optional agent tools to **list storage containers**, **list blobs in a container**, and **read blob contents** from Azure Blob Storage using a connection string or storage account name + key.
4+
5+
Registered tools (all **opt-in** — see [Tool allowlists](#2-tools--optional-tools-and-sandbox-policy)):
6+
7+
| Tool | Purpose |
8+
| ---------------------------- | --------------------------------------------------------------------------------- |
9+
| `azure_blob_list_containers` | List blob containers in the account (optional name prefix, capped results). |
10+
| `azure_blob_list_blobs` | List blobs in a container (optional blob name prefix / “folder”, capped results). |
11+
| `azure_blob_read` | Download blob bytes as UTF-8 text or base64 (size limits apply). |
12+
13+
---
14+
15+
## `openclaw.json` — plugin setup
16+
17+
The Gateway must:
18+
19+
1. **Load** this extension from disk (`plugins.load.paths`).
20+
2. **Allow** the plugin id if you use a global plugin allowlist (`plugins.allow`).
21+
3. **Enable** it and pass **credentials** (`plugins.entries.azure-blob`).
22+
4. **Expose** the optional tools via `tools.alsoAllow` (and `tools.sandbox.tools.allow` when sessions run sandboxed).
23+
24+
Use the **absolute path** to **this directory** (the folder that contains `openclaw.plugin.json`) on the **same machine** as the Gateway process. Do **not** point at `index.ts` — use the directory path to avoid plugin id mismatch warnings.
25+
26+
**Path placeholder:** replace `<ABSOLUTE_PATH_TO_AZURE_BLOB_EXTENSION>` below with your real path, for example:
27+
28+
- macOS/Linux: `/Users/you/src/openclaw/extensions/azure-blob`
29+
- Windows: `C:\\src\\openclaw\\extensions\\azure-blob`
30+
- Container: whatever path you mounted or cloned the repo to inside that environment
31+
32+
**Do not commit production secrets** — use placeholders, environment variables, or OpenClaw secret references. Restart the Gateway after changing config.
33+
34+
---
35+
36+
### 1. `plugins` — load path, allowlist, entries, credentials
37+
38+
| Key | Role |
39+
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
40+
| `plugins.load.paths` | **Directory** containing this extension (must include `openclaw.plugin.json`). Use the folder path, **not** `index.ts`. |
41+
| `plugins.allow` | If you use a global plugin allowlist, include `azure-blob` so the plugin is not blocked. |
42+
| `plugins.entries.azure-blob.enabled` | Set `true` so the plugin is active. |
43+
| `plugins.entries.azure-blob.config` | Storage auth and optional defaults (see `openclaw.plugin.json` / [Environment variables](#environment-variables)). |
44+
45+
**Example (secrets redacted):**
46+
47+
```json
48+
{
49+
"plugins": {
50+
"load": {
51+
"paths": ["<ABSOLUTE_PATH_TO_AZURE_BLOB_EXTENSION>"]
52+
},
53+
"allow": ["azure-blob"],
54+
"entries": {
55+
"azure-blob": {
56+
"enabled": true,
57+
"config": {
58+
"connectionString": "DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net",
59+
"defaultContainer": "optional-default-container"
60+
}
61+
}
62+
}
63+
}
64+
}
65+
```
66+
67+
Instead of `connectionString`, you may use `accountName` + `accountKey`, and optionally `accountUrl` (sovereign clouds / custom domain) or `defaultContainer` (used when tools omit `containerName`).
68+
69+
---
70+
71+
### 2. `tools` — optional tools and sandbox policy
72+
73+
| Key | Role |
74+
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
75+
| `tools.profile` | Base tool profile (e.g. `coding`) used with your deployment; pair it with `alsoAllow` below. |
76+
| `tools.alsoAllow` | **Required for this plugin:** optional tools are not exposed until listed here (or you allow the plugin id `azure-blob`). Include each tool name you need. |
77+
| `tools.sandbox.tools.allow` | When the **session is sandboxed**, OpenClaw applies an extra allowlist. Include every `azure_blob_*` tool that should be callable from the sandbox, plus any core tools you still need. |
78+
79+
**Example:**
80+
81+
```json
82+
{
83+
"tools": {
84+
"profile": "coding",
85+
"alsoAllow": ["azure_blob_read", "azure_blob_list_containers", "azure_blob_list_blobs"],
86+
"sandbox": {
87+
"tools": {
88+
"allow": [
89+
"read",
90+
"write",
91+
"edit",
92+
"apply_patch",
93+
"exec",
94+
"process",
95+
"group:sessions",
96+
"group:memory",
97+
"azure_blob_read",
98+
"azure_blob_list_containers",
99+
"azure_blob_list_blobs"
100+
]
101+
}
102+
}
103+
}
104+
}
105+
```
106+
107+
If you use a **non-empty** sandbox allowlist, omitting `azure_blob_list_containers` or `azure_blob_list_blobs` will **block** those tools for sandboxed sessions even if they appear in `alsoAllow`.
108+
109+
---
110+
111+
## Environment variables
112+
113+
You can keep secrets out of `openclaw.json` by setting:
114+
115+
| Variable | Maps to |
116+
| ---------------------------------------------------------- | --------------------------- |
117+
| `AZURE_STORAGE_CONNECTION_STRING` | Connection string |
118+
| `AZURE_STORAGE_ACCOUNT_NAME` / `AZURE_STORAGE_ACCOUNT_KEY` | Shared key auth |
119+
| `AZURE_STORAGE_ACCOUNT_URL` | Custom blob endpoint |
120+
| `AZURE_STORAGE_DEFAULT_CONTAINER` | Default container for tools |
121+
122+
OpenClaw also supports **secret reference objects** in config for sensitive fields (see core OpenClaw documentation).
123+
124+
---
125+
126+
## Azure Storage account checklist
127+
128+
- **Networking:** the Gateway host must reach your blob endpoint on **HTTPS (443)** if firewalls or private endpoints apply.
129+
- **Shared key access:** must be enabled if you use a connection string / account key.
130+
- **Permissions:** the key (or SAS) must allow **list** and **read** as needed for the tools you use.
131+
132+
---
133+
134+
## Minimal merged example (`plugins` + `tools` only)
135+
136+
```json
137+
{
138+
"tools": {
139+
"profile": "coding",
140+
"alsoAllow": ["azure_blob_read", "azure_blob_list_containers", "azure_blob_list_blobs"],
141+
"sandbox": {
142+
"tools": {
143+
"allow": [
144+
"read",
145+
"write",
146+
"edit",
147+
"apply_patch",
148+
"exec",
149+
"process",
150+
"group:sessions",
151+
"group:memory",
152+
"azure_blob_read",
153+
"azure_blob_list_containers",
154+
"azure_blob_list_blobs"
155+
]
156+
}
157+
}
158+
},
159+
"plugins": {
160+
"load": {
161+
"paths": ["<ABSOLUTE_PATH_TO_AZURE_BLOB_EXTENSION>"]
162+
},
163+
"allow": ["azure-blob"],
164+
"entries": {
165+
"azure-blob": {
166+
"enabled": true,
167+
"config": {
168+
"connectionString": "<DefaultEndpointsProtocol=...>"
169+
}
170+
}
171+
}
172+
}
173+
}
174+
```
175+
176+
---
177+
178+
## Security
179+
180+
- Never commit real **connection strings** or **account keys** to version control.
181+
- Rotate credentials in Azure if they were ever exposed.

‎extensions/azure-blob/index.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { definePluginEntry, type AnyAgentTool } from "openclaw/plugin-sdk/core";
2+
import {
3+
createAzureBlobListBlobsTool,
4+
createAzureBlobListContainersTool,
5+
} from "./src/blob-list-tools.js";
6+
import { createAzureBlobReadTool } from "./src/blob-read-tool.js";
7+
8+
export default definePluginEntry({
9+
id: "azure-blob",
10+
name: "Azure Blob Storage",
11+
description:
12+
"List containers, list blobs, and read blob contents from Azure Storage (azure_blob_list_containers, azure_blob_list_blobs, azure_blob_read).",
13+
register(api) {
14+
api.registerTool(createAzureBlobReadTool(api) as AnyAgentTool, { optional: true });
15+
api.registerTool(createAzureBlobListContainersTool(api) as AnyAgentTool, { optional: true });
16+
api.registerTool(createAzureBlobListBlobsTool(api) as AnyAgentTool, { optional: true });
17+
},
18+
});

‎extensions/azure-blob/openclaw.plugin.json‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"id": "azure-blob",
3+
"name": "Azure Blob Storage",
4+
"description": "List containers, list blobs, and read blob contents from Azure Storage via agent tools.",
5+
"configSchema": {
6+
"type": "object",
7+
"additionalProperties": false,
8+
"properties": {
9+
"connectionString": {
10+
"type": ["string", "object"]
11+
},
12+
"accountName": {
13+
"type": "string"
14+
},
15+
"accountKey": {
16+
"type": ["string", "object"]
17+
},
18+
"accountUrl": {
19+
"type": "string"
20+
},
21+
"defaultContainer": {
22+
"type": "string"
23+
}
24+
}
25+
},
26+
"uiHints": {
27+
"connectionString": {
28+
"label": "Azure Storage connection string",
29+
"help": "Full connection string (fallback: AZURE_STORAGE_CONNECTION_STRING).",
30+
"sensitive": true
31+
},
32+
"accountName": {
33+
"label": "Storage account name",
34+
"help": "Used with account key when no connection string is set (fallback: AZURE_STORAGE_ACCOUNT_NAME)."
35+
},
36+
"accountKey": {
37+
"label": "Storage account key",
38+
"help": "Shared key for the account (fallback: AZURE_STORAGE_ACCOUNT_KEY).",
39+
"sensitive": true
40+
},
41+
"accountUrl": {
42+
"label": "Blob service URL",
43+
"help": "Override blob endpoint (sovereign clouds, custom domain). Default: https://{account}.blob.core.windows.net"
44+
},
45+
"defaultContainer": {
46+
"label": "Default container",
47+
"help": "Optional default container when the tool omits containerName."
48+
}
49+
}
50+
}

‎extensions/azure-blob/package.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"name": "@openclaw/azure-blob",
3+
"version": "2026.3.14",
4+
"private": true,
5+
"description": "OpenClaw plugin to read files from Azure Blob Storage",
6+
"type": "module",
7+
"dependencies": {
8+
"@azure/storage-blob": "^12.31.0",
9+
"@sinclair/typebox": "0.34.48"
10+
},
11+
"openclaw": {
12+
"extensions": [
13+
"./index.ts"
14+
]
15+
}
16+
}

0 commit comments

Comments
 (0)