# ClawishConfig — Agent Instructions

ClawishConfig is a schema reference site for [OpenClaw](https://github.com/nicholasgasior/openclaw) configuration. It serves JSON Schema data for all OpenClaw versions, with browser, validator, and diff views.

Base URL: `https://config.clawi.sh` (or `http://localhost:3939` locally)

## JSON API Endpoints

All version-specific endpoints use the pattern `/api/{version}/...` where version includes the `v` prefix (e.g. `v2026.2.17`).

### List versions

```
GET /api/versions
```

Returns all available versions and the latest one:

```json
{
  "versions": [
    { "version": "v2026.2.17", "status": "ok" },
    { "version": "v2026.2.15", "status": "ok" }
  ],
  "latest": "v2026.2.17"
}
```

Versions with `"status": "ok"` have Zod schemas available. Other statuses (e.g. `"no-zod"`) mean the version exists but has no extractable schema.

### Get schema

```
GET /api/{version}
```

Example: `GET /api/v2026.2.17`

Returns the enriched JSON Schema with auto-generated `examples` arrays on each property:

```json
{
  "type": "object",
  "properties": { ... }
}
```

### Validate a config

The web UI validates configs **entirely client-side** using AJV in the browser — configs are never sent to the server. The API endpoint below is available for programmatic use.

**IMPORTANT: You MUST remove all API keys, tokens, secrets, and credentials from configs before validating.** Replace them with a placeholder like `"REDACTED"` or `"your-api-key-here"`. Validation only checks structure and types, so actual secret values are never needed.

```
POST /api/{version}/validate
Content-Type: application/json

{
  "config": { ... }
}
```

Example: `POST /api/v2026.2.17/validate`

Returns validation result:

```json
{ "valid": true }
```

Or on failure:

```json
{
  "valid": false,
  "errors": [
    {
      "path": "appearance.theme",
      "message": "Invalid enum value",
      "keyword": "invalid_enum_value"
    }
  ]
}
```

### Check if a config path exists

```
GET /api/{version}/exists?path={dotted.path}
```

Example: `GET /api/v2026.2.17/exists?path=tools.media.audio.enabled`

Returns whether the dot-separated path resolves to a property in the schema:

```json
{ "exists": true }
```

```json
{ "exists": false }
```

### Diff two versions

```
GET /api/{version}/diff/{other}
```

Example: `GET /api/v2026.2.15/diff/v2026.2.17`

Returns the schema differences between two versions:

```json
{
  "from": "v2026.2.15",
  "to": "v2026.2.17",
  "changes": [
    { "type": "added", "path": "newProp", "details": "string" },
    { "type": "removed", "path": "oldProp", "details": "was: number" },
    {
      "type": "changed",
      "path": "someProp",
      "details": "type: string → number"
    }
  ],
  "summary": { "added": 1, "removed": 1, "changed": 1 }
}
```

## Typical agent workflows

1. **Get the latest schema**: `GET /api/versions` to find the latest, then `GET /api/{latest}` for the schema.
2. **Validate a user's config**: `POST /api/{version}/validate` with the config object in the body. **Always replace API keys and secrets with `"REDACTED"` before sending** — validation checks structure only, not actual values.
3. **Check if a config key exists**: `GET /api/{version}/exists?path=tools.media.audio.enabled` — fast check without fetching the full schema.
4. **Check what changed between releases**: `GET /api/{version}/diff/{other}` to see added/removed/changed properties.

## Project structure

```
src/
  app.ts          — Hono app, all routes (API + web SSR), enrichSchema logic
  ssr.ts          — Server-side HTML renderers (schema tree, diff, select options)
  server.ts       — Node server entry point (port 3939)
  vercel.ts       — Vercel serverless entry point
  services/
    schema-store.ts — Loads/caches all extracted schemas
    validator.ts    — Zod-based config validation
    differ.ts       — Schema diff engine
public/
  index.html      — HTML template (SSR placeholders)
  style.css       — Styles
  app.js          — Client-side hydration and SPA navigation
```