---
name: alfredclaw-api
description: Manage AlfredClaw AI agents via REST API. Create, configure, start/stop agents, manage secrets, and monitor usage quotas.
metadata: {"openclaw":{"emoji":"🤖","requires":{"bins":["curl"]}}}
---

# AlfredClaw API

Manage AI agents on [AlfredClaw](https://alfredclaw.com) programmatically.

## Authentication

All requests require an API key:
```bash
export ALFREDCLAW_API_KEY="ak_live_your_key_here"
```

Create one at https://alfredclaw.com/dashboard/api-keys

## Base URL

```
https://alfredclaw.com/api/v1
```

## Agents

### List agents
```bash
curl -s "$ALFREDCLAW_API_URL/agents" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq
```

### Create an agent
```bash
# With a custom Telegram bot token
curl -s -X POST "$ALFREDCLAW_API_URL/agents" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"botToken": "123456:ABC-DEF..."}'

# With a bot from the pool
curl -s -X POST "$ALFREDCLAW_API_URL/agents" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"botId": "uuid-of-available-bot"}'
```

### Start / Stop / Restart
```bash
curl -s -X POST "$ALFREDCLAW_API_URL/agents/AGENT_ID/start" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY"

curl -s -X POST "$ALFREDCLAW_API_URL/agents/AGENT_ID/stop" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY"

curl -s -X POST "$ALFREDCLAW_API_URL/agents/AGENT_ID/restart" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY"
```

### Delete an agent
```bash
curl -s -X DELETE "$ALFREDCLAW_API_URL/agents/AGENT_ID" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY"
```

### Get agent details
```bash
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq
```

### Get logs
```bash
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID/logs?lines=50" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq .logs
```

## Configuration

### Read openclaw.json
```bash
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID/config" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq .content
```

### Update openclaw.json
```bash
curl -s -X PUT "$ALFREDCLAW_API_URL/agents/AGENT_ID/config" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "{\"agents\": {\"defaults\": {\"model\": {\"primary\": \"anthropic/claude-opus-4-5\"}}}}"}'
```

## AI Provider (OAuth)

### Start OAuth flow
```bash
# Provider: "anthropic" or "openai"
curl -s -X POST "$ALFREDCLAW_API_URL/agents/AGENT_ID/oauth/anthropic/start" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY"
# Returns: { "sessionId": "...", "authUrl": "https://..." }
```

### Complete OAuth flow
```bash
# Anthropic: user copies token from authUrl
curl -s -X POST "$ALFREDCLAW_API_URL/agents/AGENT_ID/oauth/anthropic/callback" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "...", "token": "sk-ant-oat01-..."}'

# OpenAI: user copies callback URL
curl -s -X POST "$ALFREDCLAW_API_URL/agents/AGENT_ID/oauth/openai/callback" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "...", "callbackUrl": "http://localhost..."}'
```

### Check usage quotas
```bash
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID/usage" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq
# Returns: { "provider": "anthropic", "usage": { "primary": { "usedPercent": 12.5, ... }, "secondary": { ... } } }
```

## Secrets

Secrets are injected as environment variables in the agent's container. The agent uses `$SECRET_NAME` — the LLM never sees the value.

### List secrets (values masked)
```bash
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID/secrets" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq
```

### Add a secret (triggers agent restart)
```bash
curl -s -X POST "$ALFREDCLAW_API_URL/agents/AGENT_ID/secrets" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "GITHUB_TOKEN", "value": "ghp_xxx..."}'
```

### Delete a secret (triggers agent restart)
```bash
curl -s -X DELETE "$ALFREDCLAW_API_URL/agents/AGENT_ID/secrets/GITHUB_TOKEN" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY"
```

## Files

### List workspace files
```bash
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID/files" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq .files

# Subdirectory
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID/files?path=memory" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq .files
```

### Read a file
```bash
curl -s "$ALFREDCLAW_API_URL/agents/AGENT_ID/files/SOUL.md" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq .content
```

### Write a file
```bash
curl -s -X PUT "$ALFREDCLAW_API_URL/agents/AGENT_ID/files/SOUL.md" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Soul\nYou are a helpful assistant."}'
```

## Available Bots

```bash
curl -s "$ALFREDCLAW_API_URL/bots/available" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" | jq .bots
```

## Rate Limits

- 60 requests/minute
- 1,000 requests/hour
- Rate limited responses return HTTP 429

## Error Format

```json
{ "error": { "code": "unauthorized", "message": "Invalid or missing authentication" } }
```

## Typical Flow: Spawn a New Agent

```bash
export ALFREDCLAW_API_KEY="ak_live_..."
export API="https://alfredclaw.com/api/v1"

# 1. Create agent with a Telegram bot
AGENT=$(curl -s -X POST "$API/agents" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"botToken": "YOUR_BOT_TOKEN"}')
AGENT_ID=$(echo $AGENT | jq -r '.instance.id')

# 2. Start the agent
curl -s -X POST "$API/agents/$AGENT_ID/start" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY"

# 3. Configure AI provider (Anthropic)
AUTH=$(curl -s -X POST "$API/agents/$AGENT_ID/oauth/anthropic/start" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY")
echo "Visit: $(echo $AUTH | jq -r '.authUrl')"
echo "Then paste the token:"
read TOKEN
curl -s -X POST "$API/agents/$AGENT_ID/oauth/anthropic/callback" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"sessionId\": \"$(echo $AUTH | jq -r '.sessionId')\", \"token\": \"$TOKEN\"}"

# 4. Add secrets
curl -s -X POST "$API/agents/$AGENT_ID/secrets" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "GITHUB_TOKEN", "value": "ghp_xxx"}'

# 5. Customize the agent personality
curl -s -X PUT "$API/agents/$AGENT_ID/files/SOUL.md" \
  -H "Authorization: Bearer $ALFREDCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Soul\nYou are a DevOps specialist. Be concise and technical."}'

echo "Agent $AGENT_ID is ready! Chat via Telegram."
```