Deploy a personalized AI assistant on your own server — connected via Telegram, web chat, or WebSocket — with persistent per-user memory, web browsing, email sending, and a fully configurable identity defined in a single YAML file.
nself-claw is part of the ɳClaw bundle and depends on nself-ai and nself-mux. nself-browser is optional but enables the BrowseUrl tool for web research.
# Install required dependencies first
nself license set nself_pro_...
nself plugin install ai mux
# Optional: install browser for web research capability
nself plugin install browser
# Install claw
nself plugin install claw
nself build
nself start| Variable | Required | Default | Description |
|---|---|---|---|
PLUGIN_CLAW_IDENTITY_PATH | Yes | — | Path to your identity.yaml configuration file |
PLUGIN_CLAW_ADMIN_PASSWORD | Yes | — | Password protecting admin endpoints (memory management, session list) |
PLUGIN_CLAW_MAX_MEMORY_TOKENS | No | 32000 | Maximum tokens of memory kept per user before oldest entries are pruned |
PLUGIN_CLAW_SESSION_TTL_HOURS | No | 24 | Idle session expiry in hours. Expired sessions are archived, not deleted. |
PLUGIN_CLAW_STREAM_RESPONSES | No | true | Whether to stream AI responses over WebSocket by default |
The identity file defines your assistant's persona, integrations, and enabled tools:
name: Aria
persona: |
You are Aria, a helpful assistant for Acme Corp.
You are knowledgeable, concise, and friendly.
When asked about pricing, refer users to acme.com/pricing.
# Telegram integration (optional)
telegram_token: "1234567890:AAFxxxxxxxxxxxxxxxx"
# Tools the assistant can use
tools:
- get_weather # built-in weather lookup
- BrowseUrl # web browsing (requires nself-browser)
- send_email # send via nself-mux
# AI model to use
model: gpt-4o # or claude-3-5-sonnet-20241022, gemini-1.5-pro, etc.
# Memory settings
memory:
enabled: true
summarize_after: 20 # summarize old messages after N turnsidentity.yaml with your persona and Telegram bot token (create a bot at @BotFather).PLUGIN_CLAW_IDENTITY_PATH=/etc/nself/identity.yaml and PLUGIN_CLAW_ADMIN_PASSWORD in your .env.secrets.nself build && nself start and message your Telegram bot. It responds using the configured persona and model with memory from previous conversations.| Tool | Requires | Description |
|---|---|---|
get_weather | Built-in | Look up current weather for any city |
BrowseUrl | nself-browser | Open any public URL and read its content |
send_email | nself-mux | Send email via the nself-mux mail channel |
search_web | nself-browser + PLUGIN_CLAW_SEARCH_ENGINE | Query a search engine and return top results |
ɳClaw maintains per-user memory automatically. Each conversation builds a persistent context that the assistant recalls in future sessions. Memory is stored in Postgres and summarized as it grows.
# View memory for a user
curl http://127.0.0.1:3710/claw/memory/user-uuid
# View memory stats (tokens used, entry count, last updated)
curl http://127.0.0.1:3710/claw/memory/user-uuid/stats
# Clear memory for a user
curl -X DELETE http://127.0.0.1:3710/claw/memory/user-uuid| Endpoint | Method | Description |
|---|---|---|
/claw/chat | POST | Send a message and receive a full response (non-streaming) |
/claw/chat | WS | WebSocket for streaming chat responses token-by-token |
/claw/sessions | GET | List active chat sessions with last-active timestamp |
/claw/memory/:user_id | GET | Read stored memory entries for a user |
/claw/memory/:user_id | DELETE | Clear all memory for a user |
/claw/memory/:user_id/stats | GET | Memory usage stats: token count, entry count, last updated |
/health | GET | Plugin health check including dependency status (ai, mux, browser) |
nself-claw creates tables in the np_claw schema. All tables are Hasura-tracked and accessible via GraphQL.
| Table | Key Columns | Purpose |
|---|---|---|
np_claw.sessions | id, user_id, channel, created_at, last_active_at, archived_at | Active and archived chat sessions per user |
np_claw.messages | id, session_id, role, content, tool_calls, created_at | Full conversation history including tool call traces |
np_claw.memory | id, user_id, content, token_count, type, created_at | Persistent memory entries distilled from conversations |
np_claw.threads | id, user_id, topic, summary, session_ids, created_at | Auto-detected conversation topics linking related sessions |
np_claw.tool_runs | id, message_id, tool_name, input, output, duration_ms, created_at | Audit log of every tool invocation (BrowseUrl, send_email, etc.) |
| Event | Trigger | Payload Includes |
|---|---|---|
claw.message.received | User sends a message via any channel | session_id, user_id, channel, content_preview |
claw.message.replied | Assistant finishes generating a response | session_id, latency_ms, tool_calls_count |
claw.memory.updated | A new memory entry is distilled from a session | user_id, memory_id, token_count |
claw.session.archived | A session expires or is manually closed | session_id, user_id, message_count |
claw.tool.error | A tool invocation fails (BrowseUrl timeout, email bounce, etc.) | tool_name, error, session_id |
| Option | Data ownership | Persistent memory | Custom tools | Self-hosted |
|---|---|---|---|---|
| nself-claw | Full — your Postgres | Yes — per-user, unlimited | Yes — via identity.yaml | Yes |
| OpenAI Assistants API | OpenAI stores all threads | Thread-scoped only | Function calling only | No |
| Anthropic Claude API | Anthropic stores prompts | No native memory | Tool use only | No |
| Flowise / n8n AI agents | Depends on hosting | Varies by config | Yes via nodes | Yes (self-hosted) |
Check that your telegram_token in identity.yaml is correct and the bot is active. Run nself logs claw and look for webhook registration errors. Telegram requires HTTPS — ensure your Nginx SSL is configured.
Memory is stored in np_claw.memory in Postgres — it is durable. If memory appears lost, check that np_claw schema migrations ran cleanly: run nself db migrate status.
nself-browser must be installed and running. Check nself plugin status browser and ensure the target URL is not on the denylist (PLUGIN_BROWSER_DENYLIST).
The model field in identity.yaml must exactly match a model ID known to nself-ai. Run curl http://127.0.0.1:8010/ai/v1/models to see available model IDs.
nself plugin remove clawPort: 3710 | Bundle: ɳClaw ($0.99/mo) or ɳSelf+ ($3.99/mo) | Requires: nself-ai, nself-mux | Last Updated: May 2026 | Plugin Version 1.1.0