routergateway
Gateway
The local control plane owns sessions, tools, events, and channel connections, and serves clients over WebSocket.
Version note
The usage methods and configuration on this page are based on an older version of OpenClaw, last updated on 2026.4.2. Newer versions may change behavior or configuration fields, See the OpenClaw website.
Agent field notes / 2026
OpenClaw
AI Agent Gateway suitable for any operating system.
OpenClaw Blueprint
What OpenClaw is, the role it plays, and what the ideal system can become.
OpenClaw is an open-source personal AI assistant and Gateway control system that runs on personal hardware. One Gateway connects channels, agents, workspaces, tools, and device nodes for coding, personal assistance, and continuous automation.
constructionCore characteristics
One local Gateway connects channels, agents, workspaces, and tools so a personal assistant keeps context across different entry points. Heartbeats let it take the initiative, while local memory and ongoing curation make it more useful over time. Semantic search reduces duplication and noise so retrieval stays relevant.
layers
System role
A personal assistant and coding partner
hub
Core stack
Gateway + Agents + Channels
shield_lock
Runtime boundary
Local Gateway + loopback
System map
These notes reflect my own view and information available as of 2026.4.2. See the official OpenClaw documentation for the latest version.
Architecture
Follow the path from Gateway to agents, workspaces, channels, and nodes, then understand how requests are routed and returned.
groupsagent
Agent
Receives task context and follows the agent runtime loop to call models, tools, and workspace capabilities.
folder_managedworkspace
Workspace
Provides files, context, and task boundaries for an agent, and becomes the isolation point for configuration and content.
forumchannel
Channel
Connects the assistant to existing chat surfaces such as WhatsApp, Telegram, Slack, and Discord.
neurologymodels
Models
Hosted and local models can be combined through providers, with fallback chains improving availability.
databasememory
Memory
Session state, durable files, and memory plugins provide cross-session context and knowledge retention.
extensiontools
Skills & Tools
Skills, plugins, and tools extend search, browser, file, and domain capabilities so agents can move from answering to acting.
verified_usersecurity
Security
Treat inbound messages as untrusted and use pairing, allowlists, tokens, and sandboxes to control device and tool access.
Architecture notes are based on the official Gateway, Channels, Nodes, Security, and Multi-agent documentation.Multi-agentChannelsConfiguration
Quick Start
Move from installation to onboarding, model setup, channel access, and health checks with a generic path that stays verifiable.
01
Runtime
The installer provides a supported Node.js runtime. Manual installs should use the current compatible release.
02
Platform
macOS, Linux, and Windows have supported install paths. Choose PowerShell or WSL2 according to the environment.
03
Ingress
Start the Gateway locally or inside a controlled network, then connect one channel and restrict access.
Shortest usable path
Keep installation, model setup, and channel setup separate. Every stage should produce a visible result.
- 1
Install OpenClaw
Run the platform installer or install the current package with a package manager.
- 2
Complete onboarding
Configure model access, create the default workspace, and let the Gateway finish its basic setup.
- 3
Connect one channel
Start with one direct-message surface and confirm messages reach the Gateway and an agent.
- 4
Check status and health
Use config validate, gateway status, health, and dashboard to verify the result.
terminalmacOS / Linux / WSL2
curl -fsSL https://openclaw.ai/install.sh | bashterminalWindows PowerShell
iwr -useb https://openclaw.ai/install.ps1 | iexterminalnpm install
npm install -g openclaw@latest --allow-scripts=openclawterminalConfigure / validate
openclaw onboard --install-daemon
openclaw configure
openclaw config validateterminalVerify
openclaw gateway status
openclaw health
openclaw dashboardinfo
Prove the single-agent and single-channel loop first, then add model fallbacks, multi-agent routing, and long-term memory as needed.
Installation and verification follow the official OpenClaw Getting started, Channels, and Updating documentation.Getting startedChannelsMulti-agent
My Configuration
A redacted view of the actual Gateway, Feishu, model, multi-agent, and routing structure in openclaw.json.
package_2
Open the openclaw-config repositoryThe skill packages, four workspaces, and identity files live in a public repository. The design keeps the real structure while secrets, account IDs, and group IDs remain placeholders.
Runtime
Linux host · local Gateway
Model strategy
Bailian / Antigravity / GPTSAPI / Ollama
Channel strategy
Feishu WebSocket · 4 accounts
Agent strategy
1 lead + 3 specialists
Multi-agent team design
This is not four copies of a general assistant. Intake, decisions, specialist execution, and independent verification are split into clear roles, while every agent keeps its own context, models, and skill boundary.
01
One entry point, clear decision ownership
Main receives the goal, classifies the work, assigns it, and converges the result so multiple agents do not answer or decide at the same time.
02
Role isolation keeps context clean
Each specialist has its own workspace, session, memory, and skill directory, so long-term context accumulates only around its responsibility.
03
Separate execution from verification
Coder implements while tester verifies in a different context. Editor organizes the result when it needs to become a clear deliverable.
Why the team structure helps
These gains come from clear ownership, isolated context, and verifiable handoffs, not from adding more agents alone.
account_tree
Less context pollution
Durable role files let each agent accumulate only knowledge that belongs to its job.
call_split
More parallelism
Independent implementation, testing, and documentation tasks can move together before the lead agent reconciles them.
verified
Cleaner acceptance
Separating builder from verifier gives quality decisions a more independent evidence trail.
Agent team responsibilities
| Agent | Role | Responsibility | Configuration |
|---|---|---|---|
main Jarvis | Lead agent | Owns user handoff, task assignment, and cross-agent coordination. | 6h heartbeat · 18 skills |
coder CodeMaster | Coding agent | Owns implementation, refactoring, debugging, and technical delivery. | glm5 · m2.5 / qwen3.5 / k2.5 |
tester TestNinja | Testing agent | Owns test design, automation, defect reproduction, and quality evidence. | glm5 · m2.5 / qwen3.5 / k2.5 |
editor DocMaster | Documentation agent | Owns writing, editing, information architecture, and knowledge capture. | k2.5 · qwen3.5 / m2.5 / glm5 |
Agent skill lineup
Skills are assigned by role rather than spread evenly. The lead focuses on design and coordination, while specialists focus on execution, verification, and delivery in their domain.
The repository currently contains 22 skill packages. These are two representative skills for each agent.
| Agent / Category | Skill | Description | Best for |
|---|---|---|---|
main / Jarvis Design first | brainstorming | Clarify goals, constraints, and acceptance criteria before code starts so an unexamined assumption does not enter implementation. | Best for new features, components, and behavior from zero to one. |
main / Jarvis Task governance | project-manager | Break a goal into phases, milestones, risks, and deliverables so cross-agent work has one coordination frame. | Best for multi-step and cross-role work. |
coder / CodeMaster Architecture | architecture-patterns | Use Clean Architecture, Hexagonal Architecture, and DDD to organize complex backend systems. | Best for new services, monolith decomposition, and maintainability refactors. |
coder / CodeMaster Agentic coding | coding-agent | Delegate implementation to Codex, Claude Code, and similar coding agents inside an isolated work directory. | Best for coding tasks that need multi-file exploration, edits, and iteration. |
tester / TestNinja Quality strategy | test-master | Cover unit, integration, E2E, performance, and security testing from strategy through execution and reporting. | Best for feature acceptance, regression, and test infrastructure. |
tester / TestNinja Browser verification | webapp-testing | Use Playwright against a local web app to verify behavior, console logs, screenshots, and key interactions. | Best for frontend functionality and visual regression. |
editor / DocMaster Documentation standards | docs-writer | Rewrite technical content around audience, tone, structure, and consistency so it is easier to scan and maintain. | Best for READMEs, guides, standards, and knowledge bases. |
editor / DocMaster Formal delivery | docx | Create and edit Word documents, including styles, structure, comments, and tracked changes, with a verified final format. | Best for reports, proposals, and documents that need formal layout. |
Agent team workspace
Every agent has a workspace but follows the same file protocol. The lead agent keeps the coordination view while each specialist accumulates role, memory, tool notes, and local skills inside its own directory.
data_objectRepository workspace structure
openclaw-config/
|-- openclaw.json
|-- skills/
| |-- architecture-patterns/
| |-- brainstorming/
| |-- coding-agent/
| |-- docs-writer/
| |-- project-manager/
| |-- test-master/
| |-- webapp-testing/
| +-- ... # 22 skill packages
+-- workspace/
|-- AGENTS.md # session startup + operating rules
|-- IDENTITY.md # role and impact
|-- SOUL.md # values, tone, boundaries
|-- USER.md # user preferences
|-- MEMORY.md # distilled long-term memory
|-- TOOLS.md # deployment-specific notes
|-- ERRORS.md # mistakes and corrections
|-- HEARTBEAT.md # periodic checks
|-- memory/
| +-- YYYY-MM-DD.md
|-- skills/
|-- workspace-coder/
|-- workspace-tester/
+-- workspace-editor/How the role files work together
The same file protocol answers identity, behavior, startup, preferences, memory, and local environment, so each agent's long-term context stays inspectable and portable.
JarvisMAIN AGENTIdentity comes from several Markdown files
IDENTITY.md answers who I am and what I own. SOUL.md answers how I act. AGENTS.md answers how every session starts and which rules apply. USER.md and MEMORY.md place that identity inside a real relationship and history. Together they shape stable behavior instead of relying on a single persona paragraph.
IDENTITY.mdSOUL.mdAGENTS.mdUSER.mdMEMORY.md
How IDENTITY.md is organized
The template stabilizes the skeleton without freezing personality. Every agent describes identity with the same fields, then lets SOUL.md and AGENTS.md constrain behavior.
data_objectGeneric skeleton
# IDENTITY.md
- Name: ...
- Creature: ...
- Role: ...
- Vibe: ...
- Emoji: ...
- Avatar: ...
## Role & Impact
### Core Functions
1. ...
### Work Scenarios
| Scenario | My Role |
| --- | --- |
| ... | ... |
### Communication Style
- ...data_objectmain / IDENTITY.md (actual excerpt)
# IDENTITY.md - Who Am I?
- Name: 贾维斯 (Jarvis)
- Creature: 琪哥's AI Personal Assistant + Coding Mentor
- Role: Main agent in the Agents team, managing coder / tester / editor
- Vibe: Professional yet personable, concise, and efficient
- Avatar: avatars/openclaw.png
## Role & Impact
### Core Functions
1. Coding Mentor
- Explain programming concepts and principles.
- Review code and provide improvement suggestions.
- Assist in debugging and troubleshooting.
2. Efficiency Assistant
- Automate repetitive tasks.
- Organize files and artifacts.
- Manage skills and tools.
3. Tech Partner
- Track AI and Agent technology trends.
- Discuss technical solutions and architectures.
### Work Scenarios
| Scenario | Jarvis's Role |
| --- | --- |
| Learning new concepts | Mentor - explain principles and examples |
| Coding | Reviewer - check standards and suggestions |
| Encountering bugs | Debugging partner - analyze and resolve |
| Exploring new skills | Recommender - evaluate, install, test |
### Communication Style
- Concise, direct, and actionable.
- Ask before external actions.Identity anchors for the four agents
| Agent | IDENTITY.md | SOUL.md / AGENTS.md constraint |
|---|---|---|
| main | Jarvis Team lead, efficiency partner, and coding mentor. | Professional but personable. Owns decomposition, coordination, memory maintenance, and final convergence. |
| coder | CodeMaster Coding specialist and implementation engine. | Pragmatic, direct, and code-first. Defers cross-agent coordination to main. |
| tester | TestNinja Quality specialist and test automation owner. | Meticulous, skeptical, and evidence-first. Never substitutes the builder's conclusion for independent verification. |
| editor | DocMaster Documentation and content specialist. | Clear, accurate, and reader-first. Turns completed work into a presentable deliverable. |
Configuration principles
These principles control exposure, context boundaries, model availability, and credential flow.
01
Local control plane
Keep the Gateway on loopback with token auth so the control plane is not exposed directly.
02
Agent isolation
Give every agent a separate workspace, session, and role file to prevent long-lived context pollution.
03
Model fallback
Assign a primary model and fallback chain per specialist to reduce provider or model outages.
04
Separate secrets
Keep real credentials in environment variables or secret references and publish only the redacted shape.
Redacted configuration summary
The snippet preserves the actual structure while replacing accounts, secrets, group IDs, and identifiers with non-reversible descriptions.
data_object~/.openclaw/openclaw.json
{
// Redacted summary. Secrets, IDs, and some repeated skills are omitted.
gateway: {
port: 18789,
mode: "local",
bind: "loopback",
auth: { mode: "token" },
},
channels: {
feishu: {
enabled: true,
connectionMode: "websocket",
dmPolicy: "pairing",
groupPolicy: "allowlist",
accounts: ["default", "coder", "tester", "editor"],
},
},
models: {
mode: "merge",
providers: ["bailian", "antigravity", "gptsapi", "ollama"],
},
agents: {
list: [
{
id: "main",
default: true,
identity: { name: "贾维斯" },
heartbeat: { every: "6h" },
skills: [
"feishu-doc", "feishu-drive", "feishu-perm", "feishu-wiki",
"clawhub", "github", "skill-creator", "weather", "brainstorming", "canvas-design",
"docx", "pdf", "pptx", "systematic-debugging",
"using-superpowers", "webapp-testing", "writing-plans", "xlsx",
],
},
{
id: "coder",
identity: { name: "无敌码农" },
model: { primary: "glm5", fallbacks: ["m2.5", "qwen3.5", "k2.5"] },
skills: ["feishu-doc", "feishu-drive", "feishu-perm", "feishu-wiki", "clawhub", "github", "skill-creator", "weather"],
},
{
id: "tester",
identity: { name: "无敌测试" },
model: { primary: "glm5", fallbacks: ["m2.5", "qwen3.5", "k2.5"] },
skills: ["feishu-doc", "feishu-drive", "feishu-perm", "feishu-wiki", "clawhub", "github", "skill-creator", "weather"],
},
{
id: "editor",
identity: { name: "超级编辑" },
model: { primary: "k2.5", fallbacks: ["qwen3.5", "m2.5", "glm5"] },
skills: ["feishu-doc", "feishu-drive", "feishu-perm", "feishu-wiki", "clawhub", "github", "skill-creator", "weather"],
},
],
},
bindings: [
{ agentId: "main", match: { channel: "feishu", accountId: "default" } },
{ agentId: "coder", match: { channel: "feishu", accountId: "coder" } },
{ agentId: "tester", match: { channel: "feishu", accountId: "tester" } },
{ agentId: "editor", match: { channel: "feishu", accountId: "editor" } },
],
}Configuration fields follow OpenClaw Configuration and the actual openclaw.json.openclaw-configConfigurationMulti-agent
Usage Notes
Four real practices covering agent roles, Feishu routing, skill governance, and long-term memory, plus model cost control and tool selection notes.
01
Four agents with separate roles
Let the lead agent coordinate while coding, testing, and documentation move to specialists.
What it produced
Tasks reach a matching context while the lead keeps a coordination and delivery view.
View process, risk, and boundarykeyboard_arrow_down
Process
Jarvis decomposes, assigns, and converges work. Coder, tester, and editor execute inside their own workspaces.
Risk
More agents amplify routing mistakes and duplicated context. Decision ownership must stay explicit.
Boundary
Good for clear, verifiable work. Tightly coupled or rapidly alternating work is often better in one agent.
02
Feishu routing across four accounts
Use separate Feishu accounts and bindings to send work to the matching specialist.
What it produced
Each entry resolves to a defined agent, while groups only respond to allowed mention-gated messages.
View process, risk, and boundarykeyboard_arrow_down
Process
The channel uses WebSocket with default, coder, tester, and editor accounts. DMs use pairing and groups use allowlists plus mention gating.
Risk
A live channel does not prove routing is correct. Accounts, bindings, agents, and models must be checked layer by layer.
Boundary
Useful for controlled personal or team ingress. Unknown DMs and unauthorized groups should not receive agent access.
03
Skill installation and governance
Expand agent capability without dropping unreviewed scripts directly into a workspace.
What it produced
Only skills that pass review, configuration, and testing remain available.
View process, risk, and boundarykeyboard_arrow_down
Process
Files and scripts are inspected before installation. Configuration and real calls are verified afterwards, with local usage rules captured in the workspace.
Risk
More skills do not automatically mean more capability. Duplicate, conflicting, or untested skills add maintenance and security risk.
Boundary
Good for reviewable and reversible extensions. External accounts, system changes, or public actions need separate approval.
04
Memory consolidation and long-term context
Let agents retain preferences, mistakes, project context, and long-running task clues across sessions.
What it produced
Short-term notes, long-term memory, and enhanced retrieval have separate jobs, so important lessons survive a single conversation.
View process, risk, and boundarykeyboard_arrow_down
Process
Session-memory preserves continuity, daily files capture raw notes, and MEMORY.md holds distilled conclusions. Memory-lancedb-pro is the enhanced vector retrieval path.
Risk
Memory must separate facts, preferences, and guesses. Otherwise an error can be amplified for months.
Boundary
Automated memory suits low-risk knowledge capture. Credentials, private data, and unconfirmed judgments do not belong in public or long-term memory.
Quality and cost control
Split a large task into parallel work, dispatch it through subagents, and specify the model for each delegated run. Give cheap, fast models to simple work and strong models to architecture, coding, debugging, and review. The main agent then verifies and merges the result. This avoids spending the strongest model on everything without trading away quality where it matters.
01
Judge the task boundary
Decide whether parallel work is worth it
Delegate separable research, batch edits, and independent verification. Keep tightly coupled work that needs rapid back-and-forth in the main agent.
02
Specify the model at dispatch
Do not inherit the main model by default
State the required model tier on each subagent call so simple and critical work enter different cost layers from the start.
03
Allocate by task value
Speed for simple work, accuracy for specialist work
Use cheap models for search, summaries, and classification. Use strong models for architecture, coding, debugging, testing, and documentation review.
04
Make the main agent the quality gate
Cheap execution does not lower acceptance standards
After collecting subagent results, the main agent checks evidence, runs verification, and decides whether to deliver. High-risk or irreversible actions stay with a strong-model review.
Task typeModel routeExpected output
Web search, source summaries, classification
Cheap / fast model
Return sources, conclusions, and uncertainties instead of a long paraphrase.
Parallel research, codebase exploration, first drafts
Mid-tier model
Return checkable findings and the minimum context needed for the next step.
Architecture, coding, debugging, tests, documentation review
Strong specialist model
Submit diffs, test results, screenshots, or review notes.
Final acceptance, high-risk release, irreversible action
Main agent / strongest model
The main agent verifies the evidence and makes the final call with no automatic downgrade.
Cost control is not replacing every model with the cheapest option. It is matching model capability to task value, then using the main agent's acceptance loop to protect quality.
Plugins and useful resources
These resources cover long-term memory, multi-agent collaboration, OpenClaw operations knowledge, skill discovery, and real-world examples. Third-party plugins and skills are not all officially audited. Check their source, scripts, permissions, and secret scope before installation.
0102030405
Long-term memory plugin
memory-lancedb-pro
Adds a LanceDB-backed memory layer to OpenClaw with vector plus BM25 hybrid retrieval, Cross-Encoder reranking, scope isolation, automatic capture and forgetting, and a management CLI.
Best for agents that need project context, preferences, and durable conclusions across sessions.
Multi-agent team
ClawTeam-OpenClaw
Organizes leader and worker agents on top of OpenClaw. Each worker can run in an isolated git worktree, session, and identity, with file and ZeroMQ communication paths.
Best for separable coding, research, and verification work. Model routing and acceptance ownership still need to be explicit.
Operations knowledge base
OpenClaw-Skill
A comprehensive OpenClaw agent skill whose main file and reference set cover installation, configuration, channels, the Gateway, multi-agent routing, plugins, automation, security, and memory.
Best as a structured reference while building or troubleshooting an OpenClaw setup.
Skill catalog
awesome-openclaw-skills
A categorized catalog of thousands of OpenClaw skills from ClawHub, with installation paths such as openclaw skills install and npx clawhub install.
Best for discovering new capabilities, then filtering them by source, permissions, and maintenance state.
Use-case reference
awesome-openclaw-usecases
A collection of 42 real OpenClaw use cases spanning social media, creative builds, DevOps, productivity, research, learning, and finance.
Best for workflow ideas. The repository also warns that third-party skills are unaudited, so inspect source and permissions before use.
My Scenarios
Where OpenClaw runs inside a real daily routine: a scheduled wake-up, local files, external APIs, and the result landing in the chat tool already in use.
Daily push: from cron to Feishu
One cron job wakes the main agent at 07:00 to run a script in the workspace: read the day's study plan, check the weather and watched repositories, scrape news with history de-duplication, then post a single rich-text Feishu message. The chain runs unattended, and the agent only leaves a log when the script fails.
data_objectcron/jobs.json (path and chat id elided)
{
"id": "XXXXXXXXXXXXX",
"agentId": "main",
"name": "每日推送",
"enabled": true,
"schedule": {
"kind": "cron",
"expr": "0 7 * * *",
"tz": "Asia/Shanghai"
},
"sessionTarget": "isolated",
"payload": {
"kind": "agentTurn",
"message": "运行每日推送脚本：`.../daily_push_cron.py`",
"thinking": "medium"
},
"delivery": {
"mode": "announce",
"channel": "feishu",
"to": "oc_XXXXXXXXXXXXX",
"bestEffort": false
}
}data_objectdaily_push_cron.py (excerpt)
def main():
plan = get_today_plan() # 读 Excel 学习计划
weather = get_weather() # open-meteo
github_updates = get_github_updates()
news_articles = get_news_articles() # 七个源按优先级
parts = [plan['calendar'], '', weather, '']
if github_updates: # 有新发布才插入
parts += [github_updates, '']
parts += ["【学习任务】"]
parts += [f" {task}" for task in plan['tasks']]
parts += ["", "【做题任务】", f" {plan['homework']}", ""]
encouragement = random.choice(ENCOURAGEMENT_MESSAGES)
message = '\n'.join(parts)
send_to_feishu(message, news_articles, encouragement)
def send_to_feishu(message, news_articles, encouragement):
token = get_feishu_tenant_access_token()
post = {"zh_cn": {"title": "", "content": []}}
for line in message.split('\n'): # 正文按行切成段落
post["zh_cn"]["content"].append(
[{"tag": "text", "text": line}])
for article in news_articles: # 新闻标题转成链接
post["zh_cn"]["content"].append([
{"tag": "a", "text": article['title'][:50],
"href": article['url']}])
# 其余为 HTTP 请求、返回码判断与错误日志The schedule only wakes and delivers; every piece of content comes from the script. Changing the delivery target means changing the app ID and chat id together.
Maintenance
Repeatable maintenance for Gateway health, Feishu connectivity, configuration changes, memory backups, and updates.
today01
Before use
Check the Gateway, health state, and Feishu connection to confirm the main entry works.
calendar_view_week02
Weekly memory work
Consolidate daily notes from late Sunday into MEMORY.md, including errors and durable decisions.
cleaning_services03
Workspace cleanup
Move task outputs into outcomes and remove temporary or duplicate files.
system_update04
Before update
Confirm config backups, memory export, and rollback options before previewing the OpenClaw update.
Troubleshooting map
Identify whether the problem is in the Gateway, channel, routing, or model layer before reinstalling or rewriting config.
SymptomCheckAction
Gateway unavailable
openclaw gateway status
Check the service, bind address, token, and config validation result.
Feishu has no reply
logs / dashboard
Check account connection, pairing, group allowlist, mention gate, and binding.
Wrong agent route
config get bindings
Confirm the Feishu account to agentId mapping, then inspect the matching workspace.
Repeated model failures
openclaw health
Check the provider, primary model, fallback chain, and credential availability.
Maintenance commands
terminalCheck, diagnose, and update
openclaw gateway status
openclaw health
openclaw config validate
openclaw doctor
openclaw update --dry-run
openclaw updateMemory maintenance
terminalExport and memory repository
openclaw memory-pro export --scope global --output memories-backup.json
git status
git add .
git commit -m "Update memory"
git pushshield
Keep the Gateway on loopback with token auth. Prefer Tailscale, a VPN, or SSH for remote access, and regularly review paired devices, group allowlists, skill sources, and agent tool permissions.