# deskclaw-client

Lightweight CLI client for registering bots with a [DeskClaw](https://codeup.aliyun.com/67d19229c732761f79422341/DeskClaw-Arena) exam server and triggering evaluation runs.

## Installation

```bash
pip install deskclaw-client
```

## Quick Start

```bash
# Register your bot with the exam server
deskclaw-client register \
  --server http://EXAM_SERVER_IP:8420 \
  --name my-bot \
  --url http://localhost:8080/v1/chat/completions

# Trigger a test run (waits for completion by default)
deskclaw-client run --server http://EXAM_SERVER_IP:8420 --name my-bot

# Check run status
deskclaw-client status --server http://EXAM_SERVER_IP:8420 --name my-bot

# List all registered bots
deskclaw-client list --server http://EXAM_SERVER_IP:8420
```

### Environment Variable

Set `DESKCLAW_SERVER` to avoid repeating the server URL:

```bash
export DESKCLAW_SERVER=http://EXAM_SERVER_IP:8420
deskclaw-client register --name my-bot --url http://localhost:8080/v1/chat/completions
deskclaw-client run --name my-bot
```

## Commands

| Command | Description |
|---------|-------------|
| `register` | Register a bot with the exam server |
| `run` | Trigger a test run for your bot |
| `status` | Check the status of test runs |
| `list` | List all registered bots |
| `serve` | Start a local HTTP proxy for non-HTTP agents |
| `bridges` | List available bridge types |

### Register Options

- `--server` — Exam server URL (or `DESKCLAW_SERVER` env var)
- `--name` — Unique bot name
- `--url` — Your bot's HTTP API endpoint
- `--protocol` — API protocol: `openai` (default), `anthropic`, `custom`
- `--capabilities` — Comma-separated capabilities (e.g. `text_generation,tool_use,multi_turn`)
- `--auth` — Bearer auth token (if your bot requires authentication)

## Bridge Mode (Non-HTTP Agents)

If your agent doesn't expose an HTTP API (e.g. it uses WebSocket, Socket, or stdio), use `serve` to start a local HTTP proxy that bridges between the exam server and your agent's native protocol.

```bash
deskclaw-client serve \
  --server http://EXAM_SERVER_IP:8420 \
  --name my-openclaw \
  --bridge openclaw \
  --target ws://localhost:18789 \
  --port 9090 \
  --token <your-agent-token>
```

This single command will:
1. Connect to your agent via its native protocol (WebSocket, etc.)
2. Start a local OpenAI-compatible HTTP proxy on the specified port
3. Auto-register the proxy URL with the exam server
4. Wait for test requests from the exam server

### Serve Options

- `--server` — Exam server URL (or `DESKCLAW_SERVER` env var)
- `--name` — Bot name to register
- `--bridge` — Bridge type (e.g. `openclaw`)
- `--target` — Agent native address (e.g. `ws://localhost:18789`)
- `--port` — Local proxy port (default: 9090)
- `--host` — Local proxy bind address (default: 0.0.0.0)
- `--token` — Agent auth token (bridge-specific)
- `--capabilities` — Comma-separated capabilities
- `-v` / `--verbose` — Enable debug logging

### Available Bridges

| Bridge | Transport | Description |
|--------|-----------|-------------|
| `openclaw` | WebSocket | OpenClaw agents via native WebSocket protocol |

Run `deskclaw-client bridges` to list all available bridges.

## Supported Protocols

- **OpenAI** — `/v1/chat/completions` compatible endpoints
- **Anthropic** — `/v1/messages` compatible endpoints
- **Custom** — Any HTTP endpoint (configure via exam server)
- **Bridge** — Non-HTTP agents via `deskclaw-client serve`

## License

MIT
