OpenClaw Genie
OpenClaw is a self-hosted personal AI agent gateway (MIT license, open source).
It connects LLM agents to 22+ messaging platforms natively (WhatsApp, Telegram,
Discord, Slack, Signal, iMessage, MS Teams, Matrix, and more) with 50+
integrations (Gmail, GitHub, Obsidian, Spotify, and more) through a single
Gateway process. All data stays local.
Quick Start
CODEBLOCK0
Web Control UI: http://127.0.0.1:18789/
Core Architecture
CODEBLOCK1
- - Gateway: Multiplexed port (WebSocket + HTTP + Control UI). Hot-reloads config.
- Agents: Fully isolated — own workspace, session store, memory, auth profiles, sandbox.
- Channels: 22+ native adapters run simultaneously. Deterministic routing: replies return to origin.
- Nodes: Paired companion devices that expose
canvas.*, camera.*, screen.*, device.*, notifications.* via node.invoke. - Sessions: Key format
agent:<agentId>:<channel>:<scope>:<chatId>. DM scopes: main, per-peer, per-channel-peer, per-account-channel-peer.
Agent Configuration
Workspace files in ~/.openclaw/workspace/ (default agent) or ~/.openclaw/workspace-<agentId>/:
| File | Purpose |
|---|
| INLINECODE14 | Agent personality and system prompt |
| INLINECODE15 |
Name, emoji, avatar |
|
USER.md | User profile information |
|
MEMORY.md | Curated long-term memory |
|
memory/YYYY-MM-DD.md | Daily append-only session logs |
|
TOOLS.md | Tool usage guidance |
|
BOOTSTRAP.md | One-time init tasks (deleted after first run) |
|
HEARTBEAT.md | Periodic check-in instructions |
Bootstrap injection: IDENTITY → SOUL → USER → MEMORY → daily log → skills → session.
Limits: 20,000 chars/file, 150,000 chars total (configurable).
Multi-agent config uses agents.list[] and bindings[] in openclaw.json (see references/multi-agent.md).
Configuration — openclaw.json
Location: ~/.openclaw/openclaw.json (JSON5 — comments and trailing commas OK).
CODEBLOCK2
- - Env vars:
~/.openclaw/.env, ${VAR} substitution in config strings. $include: Nested file inclusion (up to 10 levels).- Hot reload:
hybrid mode (default) — safe changes hot-apply, critical ones auto-restart. Debounce 300ms. - Strict validation: Unknown keys prevent Gateway startup.
For full reference, read references/configuration.md.
Channels Quick Reference
| Channel | Setup | Notes |
|---|
| Discord | INLINECODE31 | Bot API + Gateway; servers, DMs, threads, slash commands, voice |
| Telegram |
openclaw channels add telegram | grammY; groups, forums, inline buttons, webhook mode |
| WhatsApp |
openclaw channels add whatsapp | Baileys; QR pairing, media, polls |
| Slack |
openclaw channels add slack | Bolt SDK; socket or HTTP mode, native streaming |
| Signal |
openclaw channels add signal | signal-cli; privacy-focused, auto-daemon |
| iMessage |
openclaw channels add bluebubbles | BlueBubbles; reactions, edits, groups |
| Google Chat |
openclaw channels add googlechat | HTTP webhook app |
| IRC |
openclaw channels add irc | NickServ, channels + DMs |
| MS Teams |
openclaw plugins install @openclaw/msteams | Adaptive Cards, polls |
| Matrix |
openclaw plugins install @openclaw/matrix | E2EE, threads, rooms |
| Mattermost |
openclaw plugins install @openclaw/mattermost | Self-hosted |
| Nextcloud Talk |
openclaw plugins install @openclaw/nextcloud-talk | Self-hosted |
| WebChat | Built-in web UI | Browser-based access at gateway URL |
Access control: DM policy (pairing/allowlist/open/disabled), group policy, mention gating. Multi-account per channel supported.
For per-channel details, read references/channels.md.
Memory System
- - Daily logs:
memory/YYYY-MM-DD.md — today + yesterday loaded at session start - Long-term:
MEMORY.md — curated facts, decisions, preferences (private sessions only) - Tools:
memory_search (vector recall, ~400-token chunks) and memory_get (file reads) - Hybrid search: BM25 (exact tokens) + vector (semantic) with configurable weights
- Post-processing: MMR deduplication (lambda 0.7) + temporal decay (30-day half-life)
- Providers: auto-selects local → OpenAI → Gemini → Voyage → Mistral
- QMD backend: Optional local-first sidecar (BM25 + vectors + reranking)
- Auto flush: Silent agentic turn before context compaction preserves important memories
For full memory config, read references/memory.md.
Tools Overview
| Tool | Purpose |
|---|
| INLINECODE53 | Shell commands (sandbox/gateway/node hosts) |
| INLINECODE54 |
Background process management |
|
browser | Chromium automation (navigate, click, type, screenshot) |
|
web_search | Brave Search API queries |
|
web_fetch | URL → markdown extraction |
|
memory_search | Semantic vector search over memory |
|
memory_get | Direct memory file reads |
|
message | Cross-channel messaging (send, react, thread, pin, poll) |
|
sessions_spawn | Sub-agent runs (one-shot or persistent, up to depth 5) |
|
canvas | Node Canvas UI (HTML display on connected devices) |
|
nodes | Paired device control: camera snap/clip, screen record, notifications, canvas A2UI |
|
pdf | Native PDF analysis (up to 10 PDFs, Anthropic/Google native mode, extraction fallback) |
Access control: Profiles (minimal, coding, messaging, full), allow/deny lists, tool groups (group:fs, group:runtime, group:sessions, group:web, group:ui, group:automation).
Default profile (since v2026.3.2): onboarding defaults to messaging (not coding).
For full tools, skills, and hooks reference, read references/tools.md.
Hooks & Automation
Hooks — event-driven TypeScript handlers in <workspace>/hooks/:
| Event | Trigger |
|---|
| INLINECODE79 | Session lifecycle |
| INLINECODE80 |
Pre-injection (can mutate bootstrap files) |
|
gateway:startup | After channels load |
|
message:received/sent | Message lifecycle |
|
tool_result_persist | Synchronous tool result transform |
Automation — built into Gateway:
- - Cron: Scheduled jobs (cron expressions, intervals, one-shot). Isolated or main-session.
- Webhooks:
/hooks/wake (system events), /hooks/agent (isolated turns), custom mapped endpoints. - Heartbeat: Periodic check-ins (default 30min), batches multiple checks per turn.
Voice — macOS/iOS wake word + talk mode overlay; continuous voice on Android with ElevenLabs or system TTS; OpenAI-compatible STT endpoint (messages.tts.openai.baseUrl).
Deployment Options
CODEBLOCK3
Cloud: Fly.io, Railway, Render, GCP, Hetzner, Cloudflare Workers, Ansible.
Sandbox: Docker isolation for untrusted sessions. Modes: off, non-main, all. Scopes: session, agent, shared.
Remote access: Tailscale/VPN preferred, SSH tunnel fallback.
For full deployment guide, read references/deployment.md.
CLI Essentials
| Command | Purpose |
|---|
| INLINECODE94 | Interactive first-time setup |
| INLINECODE95 |
Service management |
|
openclaw channels add/list/status/login | Channel management |
|
openclaw models list/set/auth/scan | Model config + auth |
|
openclaw skills list/info/check | Skill management |
|
openclaw hooks list/enable/disable/install | Hook management |
|
openclaw agent --message "..." | Single agent turn |
|
openclaw agents list/add/delete | Multi-agent management |
|
openclaw sessions | List/manage sessions |
|
openclaw browser | Browser control (50+ subcommands) |
|
openclaw cron list/add/run | Scheduled jobs |
|
openclaw nodes status | List paired companion nodes |
|
openclaw devices list/approve | Manage device pairing requests |
|
openclaw config get/set/unset/validate | Config helpers (
validate checks file before startup) |
|
openclaw doctor [--fix] | Health checks + auto-repair |
|
openclaw security audit [--deep] | Security audit |
|
openclaw logs [--follow] | Tail gateway logs |
|
openclaw memory search "query" | Vector search |
|
openclaw dns setup | CoreDNS + Tailscale discovery |
|
openclaw tui | Terminal UI |
Global flags: --dev, --profile <name>, --json, --no-color
When to Read Reference Files
| If you need… | Read |
|---|
| Full openclaw.json, model providers, env vars, auth, OAuth | INLINECODE119 |
| Per-channel setup, routing, access control, streaming, multi-account |
references/channels.md |
| Memory files, vector search, QMD, embeddings, hybrid search |
references/memory.md |
| Exec, browser, skills, hooks, tool access, sub-agents, nodes |
references/tools.md |
| Docker, cloud deploy, sandboxing, native install, security |
references/deployment.md |
| Multi-agent config, bindings, broadcast, sub-agents, workspaces |
references/multi-agent.md |
OpenClaw Genie
OpenClaw 是一个自托管的个人AI代理网关（MIT许可证，开源）。
它通过单一的网关进程，将LLM代理原生连接到22+个消息平台（WhatsApp、Telegram、
Discord、Slack、Signal、iMessage、MS Teams、Matrix等），并集成50+个服务
（Gmail、GitHub、Obsidian、Spotify等）。所有数据均保留在本地。
快速开始
bash
一键安装（macOS/Linux，需要Node 22+）
curl -fsSL https://openclaw.ai/install.sh | bash
或通过npm安装
npm install -g openclaw@latest
交互式设置 — 网关、工作区、频道、技能
openclaw onboard --install-daemon
验证
openclaw status
openclaw gateway status
Web控制界面：http://127.0.0.1:18789/
核心架构
频道（WhatsApp、Discord、Telegram、Slack、Signal等）
↓
网关 ← WebSocket控制平面（端口18789），单一事实来源
↓
代理 ← 隔离的工作区、会话、记忆、工具
↓
工具 ← 执行、浏览器、技能、钩子、消息、子代理
↓
节点 ← 配套设备（macOS/iOS/Android）：摄像头、画布、屏幕
- - 网关：多路复用端口（WebSocket + HTTP + 控制界面）。配置热重载。
- 代理：完全隔离 — 拥有自己的工作区、会话存储、记忆、认证配置、沙箱。
- 频道：22+个原生适配器同时运行。确定性路由：回复返回原始来源。
- 节点：配对的配套设备，通过node.invoke暴露canvas.、camera.、screen.、device.、notifications.*。
- 会话：键格式为agent::::。私聊作用域：main、per-peer、per-channel-peer、per-account-channel-peer。
代理配置
工作区文件位于~/.openclaw/workspace/（默认代理）或~/.openclaw/workspace-/：
| 文件 | 用途 |
|---|
| SOUL.md | 代理个性与系统提示 |
| IDENTITY.md |
名称、表情符号、头像 |
| USER.md | 用户档案信息 |
| MEMORY.md | 精选的长期记忆 |
| memory/YYYY-MM-DD.md | 每日追加式会话日志 |
| TOOLS.md | 工具使用指南 |
| BOOTSTRAP.md | 一次性初始化任务（首次运行后删除） |
| HEARTBEAT.md | 定期签到指令 |
引导注入顺序：IDENTITY → SOUL → USER → MEMORY → 每日日志 → 技能 → 会话。
限制：每个文件20,000字符，总计150,000字符（可配置）。
多代理配置使用openclaw.json中的agents.list[]和bindings[]（参见references/multi-agent.md）。
配置 — openclaw.json
位置：~/.openclaw/openclaw.json（JSON5格式 — 支持注释和尾逗号）。
jsonc
{
models: { // 主要模型、备用模型、别名、图像模型
primary: anthropic/claude-sonnet-4-5,
fallbacks: [openai/gpt-4o]
},
channels: { }, // discord、telegram、whatsapp、slack、signal等
agents: { }, // 列表、默认值、绑定、广播、子代理
tools: { }, // 配置、允许/拒绝、循环检测、执行配置
skills: { }, // 条目、加载目录、安装管理器
browser: { }, // 配置、SSRF策略、可执行文件路径
sandbox: { }, // 模式（off/non-main/all）、作用域、Docker加固
gateway: { }, // 端口、认证、发现、绑定
automation: { }, // cron、webhook、心跳
hooks: { }, // 内部钩子配置
session: { }, // dmScope、重置、发送策略、维护
auth: { } // OAuth配置、密钥轮换、顺序
}
- - 环境变量：~/.openclaw/.env，配置字符串中的${VAR}替换。
- $include：嵌套文件包含（最多10层）。
- 热重载：hybrid模式（默认）— 安全变更热应用，关键变更自动重启。防抖300ms。
- 严格验证：未知键会阻止网关启动。
完整参考请阅读references/configuration.md。
频道快速参考
| 频道 | 设置 | 说明 |
|---|
| Discord | openclaw channels add discord | Bot API + 网关；服务器、私信、线程、斜杠命令、语音 |
| Telegram |
openclaw channels add telegram | grammY；群组、论坛、内联按钮、webhook模式 |
| WhatsApp | openclaw channels add whatsapp | Baileys；二维码配对、媒体、投票 |
| Slack | openclaw channels add slack | Bolt SDK；socket或HTTP模式、原生流式 |
| Signal | openclaw channels add signal | signal-cli；注重隐私、自动守护进程 |
| iMessage | openclaw channels add bluebubbles | BlueBubbles；反应、编辑、群组 |
| Google Chat | openclaw channels add googlechat | HTTP webhook应用 |
| IRC | openclaw channels add irc | NickServ、频道+私信 |
| MS Teams | openclaw plugins install @openclaw/msteams | 自适应卡片、投票 |
| Matrix | openclaw plugins install @openclaw/matrix | 端到端加密、线程、房间 |
| Mattermost | openclaw plugins install @openclaw/mattermost | 自托管 |
| Nextcloud Talk | openclaw plugins install @openclaw/nextcloud-talk | 自托管 |
| WebChat | 内置Web界面 | 通过网关URL的浏览器访问 |
访问控制：私信策略（pairing/allowlist/open/disabled）、群组策略、提及门控。支持每个频道多账号。
频道详情请阅读references/channels.md。
记忆系统
- - 每日日志：memory/YYYY-MM-DD.md — 会话开始时加载今天和昨天的日志
- 长期记忆：MEMORY.md — 精选的事实、决策、偏好（仅限私密会话）
- 工具：memorysearch（向量召回，约400个token的块）和memoryget（文件读取）
- 混合搜索：BM25（精确token）+ 向量（语义），权重可配置
- 后处理：MMR去重（lambda 0.7）+ 时间衰减（30天半衰期）
- 提供商：自动选择本地 → OpenAI → Gemini → Voyage → Mistral
- QMD后端：可选的本地优先边车（BM25 + 向量 + 重排序）
- 自动刷新：上下文压缩前的静默代理轮次，保留重要记忆
完整记忆配置请阅读references/memory.md。
工具概览
| 工具 | 用途 |
|---|
| exec | Shell命令（沙箱/网关/节点主机） |
| process |
后台进程管理 |
| browser | Chromium自动化（导航、点击、输入、截图） |
| web_search | Brave搜索API查询 |
| web_fetch | URL → Markdown提取 |
| memory_search | 记忆的语义向量搜索 |
| memory_get | 直接记忆文件读取 |
| message | 跨频道消息（发送、反应、线程、置顶、投票） |
| sessions_spawn | 子代理运行（一次性或持久，最多深度5层） |
| canvas | 节点画布UI（在连接设备上显示HTML） |
| nodes | 配对设备控制：摄像头快照/剪辑、屏幕录制、通知、画布A2UI |
| pdf | 原生PDF分析（最多10个PDF，Anthropic/Google原生模式，提取回退） |
访问控制：配置（minimal、coding、messaging、full）、允许/拒绝
