npm package: @koder.com/epicclaw-koderai-plugin
Description: EpicClaw plugin for building and managing apps in koderAI workspaces.
Latest version: 1.0.0
Deprecated: Renamed to @koder.com/files-plugin

# epicclaw-koderai-plugin

OpenClaw plugin that gives EpicClaw's AI agent direct access to koderAI workspace file operations. This is the bridge between OpenClaw (the AI runtime) and koderAI's Core API (the file system backend).

## Architecture

```
User <-> OpenClaw (AI Agent) <-> Chat Gateway (LLM Provider)
                |
                +---> epicclaw-koderai-plugin ---> Core API (File Operations)
                        (Bearer token auth)        (Azure Blob Storage)
```

- **Chat Gateway** provides the LLM (AI brain) via an OpenAI-compatible endpoint.
- **This plugin** provides the file tools (AI hands) by calling the Core API with Bearer token authentication.
- Both use the **same API key**. The key maps to a specific workspace, tenant, and user — no GUIDs are exposed to the AI or the plugin.

## How Authentication Works

The Core API has dual authentication middleware:

| Auth Method | Used By | How It Works |
|-------------|---------|--------------|
| `X-API-Key` header | Internal services (Chat Gateway AI functions) | Shared secret from config. Caller provides workspace GUIDs in the request. |
| `Authorization: Bearer <token>` | This plugin (external consumers) | Token looked up in CosmosDB. Middleware resolves WorkspaceId, UserId, TenantId automatically. |

The plugin sends a Bearer token with every request. The Core API middleware resolves the workspace context and an action filter hydrates the DTOs before the controller runs. The plugin never sees or sends any GUIDs.

## Tools Registered

| Tool | Description | API Endpoint |
|------|-------------|-------------|
| `koderai_list_files` | List files and folders in the workspace | `GET /v1/files` |
| `koderai_get_file` | Get contents of a specific file | `GET /v1/files/getFile` |
| `koderai_create_file` | Create a new file | `POST /v1/files/createFile` |
| `koderai_update_file` | Update an existing file | `PUT /v1/files/updateFile` |
| `koderai_upsert_file` | Create or update a file | `PUT /v1/files/upsertFile` |
| `koderai_delete_file` | Delete a file | `DELETE /v1/files/deleteFile` |
| `koderai_create_folder` | Create a folder | `POST /v1/files/createFolder` |
| `koderai_delete_folder` | Delete a folder and contents | `DELETE /v1/files/deleteFolder` |
| `koderai_rename_file` | Rename a file | `PUT /v1/files/renameFile` |
| `koderai_rename_folder` | Rename a folder | `PUT /v1/files/renameFolder` |
| `koderai_export_zip` | Export workspace as ZIP | `POST /v1/files/exportToZip` |
| `koderai_generate_markdown` | Combine all files into markdown | `GET /v1/files/generateMarkdown` |

All tools support an optional `container` parameter (defaults to `code`). Available containers: `code`, `screenshots`, `assets`, `builds`, `logs`, `markdown`.

## Project Structure

```
epicclaw-koderai-plugin/
├── openclaw.plugin.json     # Plugin manifest and config schema
├── package.json             # npm package metadata
├── index.ts                 # Entry point — validates config, registers tools
├── src/
│   ├── api-client.ts        # HTTP client with Bearer auth
│   └── file-tools.ts        # Tool definitions (12 tools)
├── test.ts                  # Test script for validating API calls
└── setup.sh                 # Standalone setup script (reference)
```

## Configuration

The plugin requires two config values:

| Key | Description |
|-----|-------------|
| `apiUrl` | koderAI Core API base URL |
| `apiKey` | Bearer token (same key used for the Chat Gateway LLM provider) |

These are set during VM provisioning and stored in OpenClaw's config at `plugins.entries.koderai.config`.

Config supports environment variable references:

```json
{
  "plugins": {
    "entries": {
      "koderai": {
        "enabled": true,
        "config": {
          "apiUrl": "https://koderai-api-core-dev-apollo.azurewebsites.net",
          "apiKey": "${KODERAI_API_KEY}"
        }
      }
    }
  }
}
```

## VM Provisioning

The plugin is installed and configured as part of the EpicClaw VM setup. These commands run after the OpenClaw onboard step:

```csharp
// Install the plugin
$"su - {sessionUsername} -c 'cd {openKlawDirectory} && /usr/bin/node dist/entry.js plugins install @koderai/epicclaw-koderai-plugin'",

// Configure the plugin
$"su - {sessionUsername} -c 'cd {openKlawDirectory} && /usr/bin/node dist/entry.js config set plugins.entries.koderai.enabled true'",
$"su - {sessionUsername} -c 'cd {openKlawDirectory} && /usr/bin/node dist/entry.js config set plugins.entries.koderai.config.apiUrl \"{coreApiBaseUrl}\"'",
$"su - {sessionUsername} -c 'cd {openKlawDirectory} && /usr/bin/node dist/entry.js config set plugins.entries.koderai.config.apiKey \"{userApiKey.ApiKey}\"'",
```

The API key is generated earlier in the provisioning flow via `POST /v1/apikeys` on the Core API. The same key is used for both the Chat Gateway (LLM) and this plugin (file tools).

## Testing

Run the test script against a deployed environment:

```bash
# Install dependencies
npm install
npx tsx test.ts <bearer-token> [api-url]

# Examples
npx tsx test.ts "kdr-sk-..."
npx tsx test.ts "kdr-sk-..." "https://koderai-api-core-dev-apollo.azurewebsites.net"
```

The test script exercises all 12 tools: creates files and folders, reads, updates, renames, deletes, and verifies cleanup.

## Dependencies

- `@sinclair/typebox` — JSON Schema generation for tool parameter definitions
- `openclaw` (peer) — OpenClaw plugin SDK types

## Related Repositories

- **koderAI.Core.API** — Backend file system API with dual auth middleware
- **koderAI.Chat.Gateway** — Chat gateway that serves as the LLM provider