Back to Details

zeroclaw

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ZeroClaw — Complete Reference Skill

ZeroClaw — 完整参考指南

Comprehensive operational knowledge for ZeroClaw, the fast, small, fully autonomous AI assistant infrastructure built in Rust. Source: https://github.com/zeroclaw-labs/zeroclaw | Version: 0.1.0 | Last updated: 2026-02-18
这是关于ZeroClaw的全面运维知识，ZeroClaw是一款基于Rust构建的快速、轻量、完全自主的AI助手基础设施。 来源：https://github.com/zeroclaw-labs/zeroclaw | 版本：0.1.0 | 最后更新：2026-02-18

What Is ZeroClaw

什么是ZeroClaw

  • Language: 100% Rust, single binary (~3.4-8.8MB release)
  • Memory: <5MB RAM at runtime
  • Startup: <10ms cold start
  • Platforms: ARM, x86, RISC-V — runs on $10 hardware
  • Architecture: Trait-driven, everything is swappable (providers, channels, tools, memory, tunnels, security)
  • Config: 
    ~/.zeroclaw/config.toml
    (TOML format)
  • Workspace: 
    ~/.zeroclaw/workspace/
    (SOUL.md, AGENTS.md, IDENTITY.md, USER.md, MEMORY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md)
  • Identity: ZeroClaw introduces itself as ZeroClaw, never as ChatGPT/Claude/etc.
  • 开发语言： 100% Rust，单二进制文件（发布版约3.4-8.8MB）
  • 内存占用： 运行时内存<5MB
  • 启动速度： 冷启动<10ms
  • 支持平台： ARM、x86、RISC-V — 可在10美元级硬件上运行
  • 架构： 基于Trait驱动，所有组件均可替换（提供商、渠道、工具、内存、隧道、安全模块）
  • 配置文件： 
    ~/.zeroclaw/config.toml
    （TOML格式）
  • 工作区： 
    ~/.zeroclaw/workspace/
    （包含SOUL.md、AGENTS.md、IDENTITY.md、USER.md、MEMORY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md）
  • 身份标识： ZeroClaw会以ZeroClaw的身份自我介绍，绝不会自称ChatGPT/Claude等。

Installation

安装

bash
undefined
bash
undefined

Option A: Clone + build

选项A：克隆并构建

git clone https://github.com/zeroclaw-labs/zeroclaw.git cd zeroclaw && ./bootstrap.sh
git clone https://github.com/zeroclaw-labs/zeroclaw.git cd zeroclaw && ./bootstrap.sh

Option B: Remote one-liner

选项B：远程一键安装

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/bootstrap.sh | bash

Fresh machine (install Rust + system deps)

全新机器环境（安装Rust及系统依赖）

./bootstrap.sh --install-system-deps --install-rust
./bootstrap.sh --install-system-deps --install-rust

Quick onboard after install

安装后快速初始化

zeroclaw onboard --api-key "your-api-key" --provider openrouter

---
zeroclaw onboard --api-key "your-api-key" --provider openrouter

---

CLI Reference (All Commands)

CLI参考（所有命令）

Top-Level

顶级命令

CommandPurpose
zeroclaw onboard
Initialize workspace/config (quick setup)
zeroclaw onboard --interactive
Full interactive wizard
zeroclaw onboard --channels-only
Reconfigure channels only
zeroclaw agent
Interactive AI chat
zeroclaw agent -m "Hello"
Single message mode
zeroclaw agent --provider <ID> --model <MODEL>
Override provider/model
zeroclaw agent --peripheral <board:path>
Attach hardware peripheral
zeroclaw gateway [--host H] [--port P]
Start webhook/websocket gateway
zeroclaw daemon [--host H] [--port P]
Full autonomous runtime (gateway + channels + heartbeat + scheduler)
zeroclaw status
Show full system status
zeroclaw doctor
Run diagnostics
zeroclaw providers
List 30 supported AI providers
命令用途
zeroclaw onboard
初始化工作区/配置（快速设置）
zeroclaw onboard --interactive
完整交互式向导
zeroclaw onboard --channels-only
仅重新配置交互渠道
zeroclaw agent
交互式AI聊天
zeroclaw agent -m "Hello"
单消息模式
zeroclaw agent --provider <ID> --model <MODEL>
覆盖默认提供商/模型
zeroclaw agent --peripheral <board:path>
连接硬件外设
zeroclaw gateway [--host H] [--port P]
启动webhook/websocket网关
zeroclaw daemon [--host H] [--port P]
完整自主运行时（网关+渠道+心跳+调度器）
zeroclaw status
显示系统完整状态
zeroclaw doctor
运行诊断工具
zeroclaw providers
列出30个支持的AI提供商

Service Management (launchd/systemd)

服务管理（launchd/systemd）

bash
zeroclaw service install      # Install for auto-start
zeroclaw service start        # Start service
zeroclaw service stop         # Stop service
zeroclaw service status       # Check status
zeroclaw service uninstall    # Remove service
bash
zeroclaw service install      # 安装为开机自启服务
zeroclaw service start        # 启动服务
zeroclaw service stop         # 停止服务
zeroclaw service status       # 检查服务状态
zeroclaw service uninstall    # 卸载服务

Channel Management

渠道管理

bash
zeroclaw channel list                      # List all channels + status
zeroclaw channel start                     # Start all configured channels
zeroclaw channel doctor                    # Health check channels
zeroclaw channel add <type> <json>         # Add channel (type + JSON config)
zeroclaw channel remove <name>             # Remove channel
zeroclaw channel bind-telegram <IDENTITY>  # Add Telegram user to allowlist
Note: 
channel add/remove
is not a full config mutator yet — prefer editing 
~/.zeroclaw/config.toml
directly or using 
zeroclaw onboard
.
bash
zeroclaw channel list                      # 列出所有渠道及状态
zeroclaw channel start                     # 启动所有已配置渠道
zeroclaw channel doctor                    # 渠道健康检查
zeroclaw channel add <type> <json>         # 添加渠道（类型+JSON配置）
zeroclaw channel remove <name>             # 删除渠道
zeroclaw channel bind-telegram <IDENTITY>  # 将Telegram用户添加至白名单
注意： 
channel add/remove
目前并非完整的配置修改器 — 建议直接编辑 
~/.zeroclaw/config.toml
或使用 
zeroclaw onboard
进行配置。

Cron / Scheduling

定时任务 / 调度

bash
zeroclaw cron list                              # List tasks
zeroclaw cron add "<cron-expr>" "<command>"      # Add recurring task
zeroclaw cron add --tz America/New_York "..."    # With timezone
zeroclaw cron add-at <rfc3339> "<command>"       # One-shot at timestamp
zeroclaw cron add-every <ms> "<command>"         # Fixed interval
zeroclaw cron once <delay> "<command>"           # One-shot delayed (e.g. "30m", "2h")
zeroclaw cron remove <id>
zeroclaw cron pause <id>
zeroclaw cron resume <id>
bash
zeroclaw cron list                              # 列出所有任务
zeroclaw cron add "<cron-expr>" "<command>"      # 添加周期性任务
zeroclaw cron add --tz America/New_York "..."    # 指定时区添加任务
zeroclaw cron add-at <rfc3339> "<command>"       # 在指定时间执行一次性任务
zeroclaw cron add-every <ms> "<command>"         # 按固定间隔执行任务
zeroclaw cron once <delay> "<command>"           # 延迟执行一次性任务（例如 "30m"、"2h"）
zeroclaw cron remove <id>
zeroclaw cron pause <id>
zeroclaw cron resume <id>

Models & Providers

模型与提供商

bash
zeroclaw providers                          # List all 30 providers
zeroclaw models refresh                     # Refresh model catalogs
zeroclaw models refresh --provider <ID>     # Refresh specific provider
zeroclaw models refresh --force             # Force refresh
bash
zeroclaw providers                          # 列出所有30个提供商
zeroclaw models refresh                     # 刷新模型目录
zeroclaw models refresh --provider <ID>     # 刷新指定提供商的模型
zeroclaw models refresh --force             # 强制刷新模型

Skills

技能扩展

bash
zeroclaw skills list                        # List installed skills
zeroclaw skills install <source>            # Install from GitHub URL or local path
zeroclaw skills remove <name>               # Remove skill
bash
zeroclaw skills list                        # 列出已安装的技能
zeroclaw skills install <source>            # 从GitHub URL或本地路径安装技能
zeroclaw skills remove <name>               # 删除技能

Integrations

集成功能

bash
zeroclaw integrations info <name>           # Show integration details
bash
zeroclaw integrations info <name>           # 显示集成详情

Examples: Telegram, Discord, Slack, iMessage, Matrix, Signal, WhatsApp, Email, DingTalk, Ollama

示例：Telegram、Discord、Slack、iMessage、Matrix、Signal、WhatsApp、Email、DingTalk、Ollama

undefined
undefined

Auth

身份认证

bash
zeroclaw auth login --provider <ID>         # OAuth login (e.g. openai-codex)
zeroclaw auth login --provider <ID> --device-code  # Device code flow
zeroclaw auth paste-token                   # Paste auth token (Anthropic)
zeroclaw auth setup-token                   # Alias for paste-token
zeroclaw auth refresh                       # Refresh OAuth token
zeroclaw auth logout                        # Remove auth profile
zeroclaw auth use --provider <ID>           # Set active profile
zeroclaw auth list                          # List profiles
zeroclaw auth status                        # Show token expiry info
bash
zeroclaw auth login --provider <ID>         # OAuth登录（例如openai-codex）
zeroclaw auth login --provider <ID> --device-code  # 设备码登录流程
zeroclaw auth paste-token                   # 粘贴认证令牌（Anthropic）
zeroclaw auth setup-token                   # paste-token的别名
zeroclaw auth refresh                       # 刷新OAuth令牌
zeroclaw auth logout                        # 删除认证配置文件
zeroclaw auth use --provider <ID>           # 设置活跃认证配置
zeroclaw auth list                          # 列出所有认证配置
zeroclaw auth status                        # 显示令牌过期信息

Hardware & Peripherals

硬件与外设

bash
zeroclaw hardware discover                  # Enumerate USB devices (VID/PID)
zeroclaw hardware introspect <path>         # Introspect device
zeroclaw hardware info [--chip <name>]      # Chip info via probe-rs

zeroclaw peripheral list                    # List configured boards
zeroclaw peripheral add <board> <path>      # Add board (e.g. nucleo-f401re /dev/ttyACM0)
zeroclaw peripheral flash [--port <port>]   # Flash Arduino firmware
zeroclaw peripheral setup-uno-q             # Setup Arduino Uno Q Bridge
zeroclaw peripheral flash-nucleo            # Flash Nucleo-F401RE firmware
bash
zeroclaw hardware discover                  # 枚举USB设备（VID/PID）
zeroclaw hardware introspect <path>         # 检测设备详情
zeroclaw hardware info [--chip <name>]      # 通过probe-rs获取芯片信息

zeroclaw peripheral list                    # 列出已配置的开发板
zeroclaw peripheral add <board> <path>      # 添加开发板（例如nucleo-f401re /dev/ttyACM0）
zeroclaw peripheral flash [--port <port>]   # 刷入Arduino固件
zeroclaw peripheral setup-uno-q             # 配置Arduino Uno Q桥接器
zeroclaw peripheral flash-nucleo            # 刷入Nucleo-F401RE固件

Migration

迁移工具

bash
zeroclaw migrate openclaw [--source <path>] [--dry-run]  # Import from OpenClaw
bash
zeroclaw migrate openclaw [--source <path>] [--dry-run]  # 从OpenClaw导入数据

Supported Providers (30 total)

支持的提供商（共30个）

IDDescription
openrouter
OpenRouter (default)
anthropic
Anthropic
openai
OpenAI
openai-codex
OpenAI Codex (OAuth)
ollama
Ollama [local]
gemini
Google Gemini
venice
Venice
vercel
Vercel AI Gateway
cloudflare
Cloudflare AI
moonshot
Moonshot / Kimi
opencode
OpenCode Zen
zai
Z.AI
glm
GLM (Zhipu)
minimax
MiniMax
bedrock
Amazon Bedrock
qianfan
Qianfan (Baidu)
qwen
Qwen (DashScope)
groq
Groq
mistral
Mistral
xai
xAI (Grok)
deepseek
DeepSeek
together
Together AI
fireworks
Fireworks AI
perplexity
Perplexity
cohere
Cohere
copilot
GitHub Copilot
lmstudio
LM Studio [local]
nvidia
NVIDIA NIM
ovhcloud
OVHcloud AI Endpoints
custom:<URL>
Any OpenAI-compatible endpoint
anthropic-custom:<URL>
Any Anthropic-compatible endpoint
ID描述
openrouter
OpenRouter（默认）
anthropic
Anthropic
openai
OpenAI
openai-codex
OpenAI Codex（OAuth）
ollama
Ollama [本地]
gemini
Google Gemini
venice
Venice
vercel
Vercel AI Gateway
cloudflare
Cloudflare AI
moonshot
Moonshot / Kimi
opencode
OpenCode Zen
zai
Z.AI
glm
GLM（智谱）
minimax
MiniMax
bedrock
Amazon Bedrock
qianfan
千帆（百度）
qwen
通义千问（DashScope）
groq
Groq
mistral
Mistral
xai
xAI（Grok）
deepseek
DeepSeek
together
Together AI
fireworks
Fireworks AI
perplexity
Perplexity
cohere
Cohere
copilot
GitHub Copilot
lmstudio
LM Studio [本地]
nvidia
NVIDIA NIM
ovhcloud
OVHcloud AI Endpoints
custom:<URL>
任何兼容OpenAI的端点
anthropic-custom:<URL>
任何兼容Anthropic的端点

Custom Provider Setup

自定义提供商配置

toml
undefined
toml
undefined

OpenAI-compatible

兼容OpenAI的提供商

default_provider = "custom:https://your-api.com" api_key = "your-api-key" default_model = "your-model"
default_provider = "custom:https://your-api.com" api_key = "your-api-key" default_model = "your-model"

Anthropic-compatible

兼容Anthropic的提供商

default_provider = "anthropic-custom:https://your-api.com" api_key = "your-api-key" default_model = "your-model"

---
default_provider = "anthropic-custom:https://your-api.com" api_key = "your-api-key" default_model = "your-model"

---

Channels (14 supported)

交互渠道（支持14种）

Channel Matrix

渠道矩阵

ChannelConfig SectionAccess Control FieldSetup
CLIalways enabledn/aBuilt-in
Telegram
[channels_config.telegram]
allowed_users
zeroclaw onboard
Discord
[channels_config.discord]
allowed_users
zeroclaw onboard
Slack
[channels_config.slack]
allowed_users
zeroclaw onboard
Mattermost
[channels_config.mattermost]
allowed_users
Manual config
Webhook
[channels_config.webhook]
secret
(optional)		Manual / onboard
iMessage
[channels_config.imessage]
allowed_contacts
macOS only
Matrix
[channels_config.matrix]
allowed_users
zeroclaw onboard
Signal
[channels_config.signal]
allowed_from
Manual config
WhatsApp
[channels_config.whatsapp]
allowed_numbers
zeroclaw onboard
Email
[channels_config.email]
allowed_senders
Manual config
IRC
[channels_config.irc]
allowed_users
zeroclaw onboard
Lark
[channels_config.lark]
allowed_users
Manual config
DingTalk
[channels_config.dingtalk]
allowed_users
zeroclaw onboard
渠道配置节访问控制字段设置方式
CLI始终启用无内置
Telegram
[channels_config.telegram]
allowed_users
zeroclaw onboard
Discord
[channels_config.discord]
allowed_users
zeroclaw onboard
Slack
[channels_config.slack]
allowed_users
zeroclaw onboard
Mattermost
[channels_config.mattermost]
allowed_users
手动配置
Webhook
[channels_config.webhook]
secret
（可选）		手动/向导配置
iMessage
[channels_config.imessage]
allowed_contacts
仅支持macOS
Matrix
[channels_config.matrix]
allowed_users
zeroclaw onboard
Signal
[channels_config.signal]
allowed_from
手动配置
WhatsApp
[channels_config.whatsapp]
allowed_numbers
zeroclaw onboard
Email
[channels_config.email]
allowed_senders
手动配置
IRC
[channels_config.irc]
allowed_users
zeroclaw onboard
Lark
[channels_config.lark]
allowed_users
手动配置
DingTalk
[channels_config.dingtalk]
allowed_users
zeroclaw onboard

Deny-by-Default Allowlist Rules

默认拒绝的白名单规则

  • []
    (empty) = deny all
  • ["*"]
    = allow all (not recommended for production)
  • ["123456789", "username"]
    = exact match only
  • []
    （空数组）= 拒绝所有
  • ["*"]
    = 允许所有（生产环境不推荐）
  • ["123456789", "username"]
    = 仅精确匹配指定用户

Telegram Setup

Telegram配置

toml
[channels_config.telegram]
bot_token = "your-bot-token"
allowed_users = []
bash
undefined
toml
[channels_config.telegram]
bot_token = "your-bot-token"
allowed_users = []
bash
undefined

1. Get bot token from @BotFather on Telegram

1. 在Telegram的@BotFather处获取bot令牌

2. Add config above to ~/.zeroclaw/config.toml

2. 将上述配置添加到~/.zeroclaw/config.toml

3. Bind your user:

3. 绑定你的用户：

zeroclaw channel bind-telegram <USER_ID_OR_USERNAME>
zeroclaw channel bind-telegram <USER_ID_OR_USERNAME>

4. Start:

4. 启动服务：

zeroclaw daemon

**Important:** Telegram uses long-polling — no inbound port or public IP required. Only one poller per bot token allowed (don't run multiple daemons).
zeroclaw daemon

**重要提示：** Telegram使用长轮询机制 — 无需入站端口或公网IP。每个bot令牌仅允许一个轮询器（不要运行多个daemon进程）。

Discord Setup

Discord配置

  1. Go to https://discord.com/developers/applications
  2. Create app, enable Bot, copy token
  3. Enable MESSAGE CONTENT intent
  4. Run 
    zeroclaw onboard
  1. 访问https://discord.com/developers/applications
  2. 创建应用，启用Bot功能，复制令牌
  3. 启用MESSAGE CONTENT权限
  4. 运行
    zeroclaw onboard

Slack Setup

Slack配置

  1. Go to https://api.slack.com/apps
  2. Create app, add Bot Token Scopes, install
  3. Run 
    zeroclaw onboard
  1. 访问https://api.slack.com/apps
  2. 创建应用，添加Bot令牌权限，完成安装
  3. 运行
    zeroclaw onboard

Mattermost Setup

Mattermost配置

toml
[channels_config.mattermost]
url = "https://mm.your-domain.com"
bot_token = "your-bot-access-token"
channel_id = "your-channel-id"
allowed_users = ["user-id-1"]
thread_replies = true
mention_only = true
toml
[channels_config.mattermost]
url = "https://mm.your-domain.com"
bot_token = "your-bot-access-token"
channel_id = "your-channel-id"
allowed_users = ["user-id-1"]
thread_replies = true
mention_only = true

WhatsApp Setup

WhatsApp配置

toml
[channels_config.whatsapp]
access_token = "your-access-token"
phone_number_id = "your-phone-number-id"
verify_token = "your-verify-token"
allowed_numbers = ["+1234567890"]
WhatsApp requires a public URL (webhook) — use a tunnel (Tailscale/ngrok/Cloudflare).
toml
[channels_config.whatsapp]
access_token = "your-access-token"
phone_number_id = "your-phone-number-id"
verify_token = "your-verify-token"
allowed_numbers = ["+1234567890"]
WhatsApp需要公网URL（webhook）— 可使用隧道工具（Tailscale/ngrok/Cloudflare）。

Signal Setup

Signal配置

toml
[channels_config.signal]
http_url = "http://127.0.0.1:8686"
account = "+1234567890"
allowed_from = ["+1987654321"]
ignore_attachments = true
ignore_stories = true
toml
[channels_config.signal]
http_url = "http://127.0.0.1:8686"
account = "+1234567890"
allowed_from = ["+1987654321"]
ignore_attachments = true
ignore_stories = true

Lark Setup

Lark配置

toml
[channels_config.lark]
app_id = "your-app-id"
app_secret = "your-app-secret"
allowed_users = ["your-user-id"]
receive_mode = "websocket"   # or "webhook"
toml
[channels_config.lark]
app_id = "your-app-id"
app_secret = "your-app-secret"
allowed_users = ["your-user-id"]
receive_mode = "websocket"   # 或 "webhook"

In-Chat Commands (Telegram/Discord)

聊天内命令（Telegram/Discord）

While channel server is running, users can execute:
  • /models
    — show available providers
  • /models <provider>
    — switch provider (sender-scoped)
  • /model
    — show current model
  • /model <model-id>
    — switch model (sender-scoped)
Switching clears that sender's conversation history to avoid cross-model contamination.
渠道服务器运行时，用户可执行以下命令：
  • /models
    — 显示可用提供商
  • /models <provider>
    — 切换提供商（仅对当前发送者生效）
  • /model
    — 显示当前使用的模型
  • /model <model-id>
    — 切换模型（仅对当前发送者生效）
切换模型会清除该发送者的对话历史，避免跨模型污染。

Config Reference (
~/.zeroclaw/config.toml
)

配置参考（
~/.zeroclaw/config.toml
）

Core

核心配置

KeyDefaultNotes
default_provider
openrouter
Provider ID or alias
default_model
anthropic/claude-sonnet-4.5
Model routed through provider
default_temperature
0.7
0.0-2.0
键默认值说明
default_provider
openrouter
提供商ID或别名
default_model
anthropic/claude-sonnet-4.5
通过提供商路由的模型
default_temperature
0.7
取值范围0.0-2.0

Gateway

网关配置

KeyDefaultPurpose
gateway.host
127.0.0.1
Bind address
gateway.port
3000
Listen port
gateway.require_pairing
true
Require pairing for auth
gateway.allow_public_bind
false
Block accidental public exposure
键默认值用途
gateway.host
127.0.0.1
绑定地址
gateway.port
3000
监听端口
gateway.require_pairing
true
要求配对认证
gateway.allow_public_bind
false
阻止意外公网暴露

Memory

内存配置

KeyDefaultPurpose
memory.backend
sqlite
sqlite
, 
lucid
, 
markdown
, 
none
memory.auto_save
true
Auto-persist
memory.embedding_provider
none
none
, 
openai
, or custom
memory.vector_weight
0.7
Hybrid search vector weight
memory.keyword_weight
0.3
Hybrid search keyword weight
键默认值用途
memory.backend
sqlite
可选值：
sqlite
、
lucid
、
markdown
、
none
memory.auto_save
true
自动持久化
memory.embedding_provider
none
可选值：
none
、
openai
或自定义提供商
memory.vector_weight
0.7
混合搜索的向量权重
memory.keyword_weight
0.3
混合搜索的关键词权重

Autonomy / Security

自主性 / 安全配置

KeyDefaultPurpose
autonomy.level
supervised
readonly
, 
supervised
, 
full
autonomy.workspace_only
true
Restrict to workspace
autonomy.allowed_commands
[git, npm, cargo, ls, cat, grep, find, echo, pwd, wc, head, tail]
Whitelisted commands
autonomy.max_actions_per_hour
20
Rate limit
autonomy.max_cost_per_day_cents
500
Cost cap
键默认值用途
autonomy.level
supervised
可选值：
readonly
、
supervised
、
full
autonomy.workspace_only
true
限制访问工作区
autonomy.allowed_commands
[git, npm, cargo, ls, cat, grep, find, echo, pwd, wc, head, tail]
白名单命令
autonomy.max_actions_per_hour
20
速率限制
autonomy.max_cost_per_day_cents
500
每日成本上限（单位：美分）

Agent

Agent配置

KeyDefault
agent.max_tool_iterations
10
agent.max_history_messages
50
agent.parallel_tools
false
键默认值
agent.max_tool_iterations
10
agent.max_history_messages
50
agent.parallel_tools
false

Browser Control

浏览器控制配置

KeyDefaultPurpose
browser.enabled
false
Enable browser tools
browser.allowed_domains
[]
Domain allowlist (
["*"]
for all)
browser.backend
agent_browser
agent_browser
, 
rust_native
, 
computer_use
, 
auto
browser.native_headless
true
Headless mode for rust_native backend
browser.native_webdriver_url
http://127.0.0.1:9515
WebDriver endpoint for rust_native
browser.native_chrome_path
(auto)Optional explicit Chrome binary path
browser.computer_use.endpoint
http://127.0.0.1:8787/v1/actions
Computer-use sidecar endpoint
browser.computer_use.timeout_ms
15000
Per-action timeout
browser.computer_use.allow_remote_endpoint
false
Only allow localhost sidecar
键默认值用途
browser.enabled
false
启用浏览器工具
browser.allowed_domains
[]
域名白名单（
["*"]
表示允许所有）
browser.backend
agent_browser
可选值：
agent_browser
、
rust_native
、
computer_use
、
auto
browser.native_headless
true
rust_native后端的无头模式
browser.native_webdriver_url
http://127.0.0.1:9515
rust_native后端的WebDriver端点
browser.native_chrome_path
自动检测可选的Chrome二进制文件路径
browser.computer_use.endpoint
http://127.0.0.1:8787/v1/actions
Computer-use侧车服务器端点
browser.computer_use.timeout_ms
15000
每个操作的超时时间
browser.computer_use.allow_remote_endpoint
false
仅允许本地侧车端点

HTTP Requests

HTTP请求配置

KeyDefaultPurpose
http_request.enabled
false
Enable HTTP request tool
http_request.allowed_domains
[]
Domain allowlist (
["*"]
for all)
http_request.max_response_size
0
Max response bytes (0 = unlimited)
http_request.timeout_secs
0
Request timeout (0 = unlimited)
键默认值用途
http_request.enabled
false
启用HTTP请求工具
http_request.allowed_domains
[]
域名白名单（
["*"]
表示允许所有）
http_request.max_response_size
0
最大响应字节数（0表示无限制）
http_request.timeout_secs
0
请求超时时间（0表示无限制）

Other Notable Sections

其他重要配置节

  • [runtime]
    — native or docker sandbox
  • [reliability]
    — provider retries, backoff, fallback
  • [scheduler]
    — task scheduling (max 64 tasks, 4 concurrent)
  • [heartbeat]
    — periodic check-ins (disabled by default)
  • [cron]
    — cron scheduling
  • [tunnel]
    — provider: 
    none
    , 
    tailscale
    , 
    ngrok
    , 
    cloudflare
  • [composio]
    — Composio integration (250+ app integrations)
  • [secrets]
    — encrypted secrets
  • [web_search]
    — DuckDuckGo by default
  • [proxy]
    — HTTP proxy support
  • [cost]
    — daily/monthly limits, per-model pricing
  • [peripherals]
    — hardware boards
  • [runtime]
    — 原生或Docker沙箱
  • [reliability]
    — 提供商重试、退避、降级策略
  • [scheduler]
    — 任务调度（最多64个任务，4个并发）
  • [heartbeat]
    — 周期性检查（默认禁用）
  • [cron]
    — 定时任务调度
  • [tunnel]
    — 隧道提供商：
    none
    、
    tailscale
    、
    ngrok
    、
    cloudflare
  • [composio]
    — Composio集成（支持250+应用）
  • [secrets]
    — 加密密钥存储
  • [web_search]
    — 默认使用DuckDuckGo
  • [proxy]
    — HTTP代理支持
  • [cost]
    — 每日/每月限额、按模型定价
  • [peripherals]
    — 硬件开发板配置

Browser Control Setup

浏览器控制设置

Browser Backends

浏览器后端

BackendMechanismRuntime RequirementBuild Requirement
agent_browser
(default)		Calls Vercel's 
agent-browser
CLI as subprocess
agent-browser
on 
$PATH
None (default build)
rust_native
In-process WebDriver via fantocciniChromeDriver running
cargo build --release --features browser-native
computer_use
HTTP POST to sidecar for OS-level mouse/keyboard/screenComputer-use sidecar serverNone
auto
Auto-detects best available backendDepends on what's installedNone
后端实现机制运行时要求构建要求
agent_browser
（默认）		调用Vercel的
agent-browser
CLI作为子进程
agent-browser
需在
$PATH
中		无（默认构建包含）
rust_native
通过fantoccini进程内调用WebDriverChromeDriver需运行
cargo build --release --features browser-native
computer_use
通过HTTP POST请求侧车服务实现系统级鼠标/键盘/屏幕控制需运行Computer-use侧车服务器无
auto
自动检测最佳可用后端取决于已安装的组件无

Recommended Setup: 
agent_browser
with Visible Chrome Window

推荐配置：
agent_browser
+ 可见Chrome窗口

This gives you a visible Chrome window that pops up on your desktop (like OpenClaw) — you can watch the AI browse, log into sites, and the profile persists cookies/sessions.
这种配置会在桌面弹出可见的Chrome窗口（类似OpenClaw）— 你可以观察AI浏览网页、登录站点，且配置文件会持久化Cookie和会话。

Step 1: Install agent-browser

步骤1：安装agent-browser

bash
npm install -g agent-browser
bash
npm install -g agent-browser

Verify:

验证安装：

agent-browser --version
undefined
agent-browser --version
undefined

Step 2: Configure agent-browser for headed mode

步骤2：配置agent-browser为可视模式

Create 
~/.agent-browser/config.json
:
json
{
  "headed": true,
  "profile": "~/.agent-browser/profile",
  "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}
CRITICAL: The 
executablePath
is required for headed (visible) mode. By default, agent-browser uses Playwright's bundled Chromium (
~/Library/Caches/ms-playwright/chromium-*/
) which ignores the 
headed
flag and always runs headless. Pointing to your real Google Chrome install fixes this.
Common Chrome paths:
  • macOS: 
    /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • Linux: 
    /usr/bin/google-chrome
    or 
    /usr/bin/chromium
  • Windows: 
    C:\Program Files\Google\Chrome\Application\chrome.exe
The 
profile
path gives you persistent cookies/logins across sessions.
创建
~/.agent-browser/config.json
：
json
{
  "headed": true,
  "profile": "~/.agent-browser/profile",
  "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}
关键提示： 
executablePath
是启用可视模式的必要配置。默认情况下，agent-browser使用Playwright捆绑的Chromium（
~/Library/Caches/ms-playwright/chromium-*/
），它会忽略
headed
标志并始终以无头模式运行。指向你本地安装的Google Chrome可修复此问题。
常见Chrome路径：
  • macOS： 
    /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
  • Linux： 
    /usr/bin/google-chrome
    或 
    /usr/bin/chromium
  • Windows： 
    C:\Program Files\Google\Chrome\Application\chrome.exe
profile
路径用于跨会话持久化Cookie和登录状态。

Step 3: Configure ZeroClaw

步骤3：配置ZeroClaw

In 
~/.zeroclaw/config.toml
:
toml
[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"
在
~/.zeroclaw/config.toml
中添加：
toml
[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"

Step 4: Start daemon with headed env var (belt and suspenders)

步骤4：使用可视环境变量启动daemon

bash
AGENT_BROWSER_HEADED=true zeroclaw daemon
Or for service install, export the env var in your shell profile first.
bash
AGENT_BROWSER_HEADED=true zeroclaw daemon
如果是作为服务安装，可先在shell配置文件中导出该环境变量。

agent-browser CLI Reference

agent-browser CLI参考

bash
agent-browser open <url>              # Navigate to URL
agent-browser click <selector>        # Click element
agent-browser type <sel> <text>       # Type into element
agent-browser fill <sel> <text>       # Clear and fill
agent-browser screenshot [path]       # Take screenshot
agent-browser snapshot                # Accessibility tree with @refs (for AI)
agent-browser eval <js>               # Run JavaScript
agent-browser close                   # Close browser
agent-browser --headed open <url>     # Force visible window
agent-browser --session <name> ...    # Isolated session
agent-browser --profile <path> ...    # Persistent browser profile
bash
agent-browser open <url>              # 导航至指定URL
agent-browser click <selector>        # 点击元素
agent-browser type <sel> <text>       # 在元素中输入文本
agent-browser fill <sel> <text>       # 清空并填充元素
agent-browser screenshot [path]       # 截图
agent-browser snapshot                # 获取可访问性树（供AI使用）
agent-browser eval <js>               # 运行JavaScript
agent-browser close                   # 关闭浏览器
agent-browser --headed open <url>     # 强制启用可视窗口
agent-browser --session <name> ...    # 隔离会话
agent-browser --profile <path> ...    # 持久化浏览器配置文件

agent-browser Environment Variables

agent-browser环境变量

VarPurpose
AGENT_BROWSER_HEADED
Show browser window (not headless)
AGENT_BROWSER_SESSION
Session name
AGENT_BROWSER_SESSION_NAME
Auto-save/restore state persistence
AGENT_BROWSER_PROFILE
Persistent browser profile path
AGENT_BROWSER_EXECUTABLE_PATH
Custom browser binary
AGENT_BROWSER_PROXY
Proxy server URL
AGENT_BROWSER_CONFIG
Path to config file
AGENT_BROWSER_AUTO_CONNECT
Auto-discover running Chrome
AGENT_BROWSER_STREAM_PORT
WebSocket streaming port
变量用途
AGENT_BROWSER_HEADED
显示浏览器窗口（非无头模式）
AGENT_BROWSER_SESSION
会话名称
AGENT_BROWSER_SESSION_NAME
自动保存/恢复状态
AGENT_BROWSER_PROFILE
持久化浏览器配置文件路径
AGENT_BROWSER_EXECUTABLE_PATH
自定义浏览器二进制文件路径
AGENT_BROWSER_PROXY
代理服务器URL
AGENT_BROWSER_CONFIG
配置文件路径
AGENT_BROWSER_AUTO_CONNECT
自动发现运行中的Chrome
AGENT_BROWSER_STREAM_PORT
WebSocket流端口

Browser Security Model

浏览器安全模型

  • All URLs pass through 
    validate_url()
    which enforces 
    allowed_domains
  • file://
    scheme is blocked (prevents local file exfiltration)
  • Private/reserved IP ranges are rejected
  • For 
    computer_use
    : coordinate validation, endpoint must be localhost unless 
    allow_remote_endpoint = true
  • 所有URL都会通过
    validate_url()
    验证，确保符合
    allowed_domains
    规则
  • 阻止
    file://
    协议（防止本地文件泄露）
  • 拒绝私有/保留IP范围
  • 对于
    computer_use
    ：会进行协同验证，除非
    allow_remote_endpoint = true
    ，否则仅允许本地端点

Troubleshooting Browser

浏览器故障排除

ProblemSolution
Browser opens but invisible (headless)Set 
executablePath
in 
~/.agent-browser/config.json
to real Chrome, not Playwright Chromium
"domain not in allowed list"Set 
browser.allowed_domains = ["*"]
in ZeroClaw config and restart daemon
agent-browser not found
npm install -g agent-browser
Browser closes immediatelyCheck 
agent-browser --version
; ensure Chrome is installed
Stale session
agent-browser close
then retry
问题解决方案
浏览器打开但不可见（无头模式）在
~/.agent-browser/config.json
中设置
executablePath
为本地Chrome路径，而非Playwright捆绑的Chromium
"domain not in allowed list"在ZeroClaw配置中设置
browser.allowed_domains = ["*"]
并重启daemon
agent-browser未找到执行
npm install -g agent-browser
重新安装
浏览器立即关闭检查
agent-browser --version
；确保Chrome已安装
会话过期执行
agent-browser close
后重试

Full Autonomy Setup (Max Power Mode)

完全自主模式设置（最大权限）

To unlock all capabilities and remove all restrictions:
要解锁所有功能并移除所有限制，请按以下配置设置：

Config (
~/.zeroclaw/config.toml
)

配置文件（
~/.zeroclaw/config.toml
）

toml
[autonomy]
level = "full"
workspace_only = false
allowed_commands = ["*"]
forbidden_paths = []
max_actions_per_hour = 200
max_cost_per_day_cents = 5000
require_approval_for_medium_risk = false
block_high_risk_commands = false
auto_approve = [
    "shell",
    "file_read",
    "file_write",
    "memory_store",
    "memory_recall",
    "memory_forget",
]
always_ask = []

[agent]
compact_context = false
max_tool_iterations = 50
max_history_messages = 200
parallel_tools = true
tool_dispatcher = "auto"

[scheduler]
enabled = true
max_tasks = 128
max_concurrent = 8

[heartbeat]
enabled = true
interval_minutes = 30

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"

[http_request]
enabled = true
allowed_domains = ["*"]
max_response_size = 10485760
timeout_secs = 30

[composio]
enabled = true
entity_id = "default"

[web_search]
enabled = true
provider = "duckduckgo"
max_results = 5
timeout_secs = 15
toml
[autonomy]
level = "full"
workspace_only = false
allowed_commands = ["*"]
forbidden_paths = []
max_actions_per_hour = 200
max_cost_per_day_cents = 5000
require_approval_for_medium_risk = false
block_high_risk_commands = false
auto_approve = [
    "shell",
    "file_read",
    "file_write",
    "memory_store",
    "memory_recall",
    "memory_forget",
]
always_ask = []

[agent]
compact_context = false
max_tool_iterations = 50
max_history_messages = 200
parallel_tools = true
tool_dispatcher = "auto"

[scheduler]
enabled = true
max_tasks = 128
max_concurrent = 8

[heartbeat]
enabled = true
interval_minutes = 30

[browser]
enabled = true
allowed_domains = ["*"]
backend = "agent_browser"

[http_request]
enabled = true
allowed_domains = ["*"]
max_response_size = 10485760
timeout_secs = 30

[composio]
enabled = true
entity_id = "default"

[web_search]
enabled = true
provider = "duckduckgo"
max_results = 5
timeout_secs = 15

External Dependencies for Full Power

完全自主模式的外部依赖

bash
undefined
bash
undefined

Browser control (visible Chrome window)

浏览器控制（可视Chrome窗口）

npm install -g agent-browser
npm install -g agent-browser

agent-browser config (~/.agent-browser/config.json)

agent-browser配置（~/.agent-browser/config.json）

{ "headed": true, "profile": "~/.agent-browser/profile", "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" }
{ "headed": true, "profile": "~/.agent-browser/profile", "executablePath": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" }

Start daemon with headed browser

启动带可视浏览器的daemon

AGENT_BROWSER_HEADED=true zeroclaw daemon
undefined
AGENT_BROWSER_HEADED=true zeroclaw daemon
undefined

What Each Setting Unlocks

各配置项解锁的功能

SettingWhat it does
autonomy.level = "full"
No approval needed for any action
autonomy.workspace_only = false
Can access files anywhere on system
autonomy.allowed_commands = ["*"]
Can run any shell command
autonomy.forbidden_paths = []
No path restrictions
block_high_risk_commands = false
Destructive commands allowed
auto_approve = [all tools]
All tools run without confirmation
agent.max_tool_iterations = 50
5x more tool calls per task
agent.parallel_tools = true
Run multiple tools simultaneously
browser.enabled = true
Browser automation active
browser.allowed_domains = ["*"]
Can browse any website
http_request.enabled = true
Can make HTTP requests to any domain
composio.enabled = true
250+ app integrations (Gmail, Calendar, GitHub, etc.)
heartbeat.enabled = true
Proactive background checks every 30 min
scheduler.max_concurrent = 8
8 parallel scheduled tasks
配置项功能说明
autonomy.level = "full"
任何操作无需审批
autonomy.workspace_only = false
可访问系统内所有文件
autonomy.allowed_commands = ["*"]
可运行任何Shell命令
autonomy.forbidden_paths = []
无路径限制
block_high_risk_commands = false
允许执行高风险命令
auto_approve = [all tools]
所有工具无需确认即可运行
agent.max_tool_iterations = 50
每个任务最多可调用50次工具（默认是10次）
agent.parallel_tools = true
可同时运行多个工具
browser.enabled = true
启用浏览器自动化
browser.allowed_domains = ["*"]
可浏览任何网站
http_request.enabled = true
可向任何域名发送HTTP请求
composio.enabled = true
支持250+应用集成（Gmail、Calendar、GitHub等）
heartbeat.enabled = true
每30分钟进行一次主动后台检查
scheduler.max_concurrent = 8
最多可同时运行8个定时任务

Security Warning

安全警告

Full autonomy mode removes all guardrails. The agent can:
  • Run any command on your system
  • Read/write any file
  • Browse any website with your Chrome profile (cookies, logins)
  • Make HTTP requests to any domain
  • Execute shell commands without approval
Only use this on trusted, personal machines. For shared/production use, keep 
supervised
mode with explicit allowlists.
完全自主模式会移除所有安全防护。Agent可以：
  • 在你的系统上运行任何命令
  • 读取/写入任何文件
  • 使用你的Chrome配置文件浏览任何网站（包含Cookie、登录状态）
  • 向任何域名发送HTTP请求
  • 无需审批即可执行Shell命令
仅在可信的个人设备上使用此模式。对于共享/生产环境，请保持
supervised
模式并使用明确的白名单。

Operations Runbook

运维手册

Runtime Modes

运行模式

ModeCommandWhen
Foreground runtime
zeroclaw daemon
Local debugging
Gateway only
zeroclaw gateway
Webhook testing
User service
zeroclaw service install && start
Persistent runtime
模式命令使用场景
前台运行
zeroclaw daemon
本地调试
仅网关
zeroclaw gateway
Webhook测试
用户服务
zeroclaw service install && start
持久化运行

Operator Checklist

运维检查清单

bash
zeroclaw status          # Check config
zeroclaw doctor          # Run diagnostics
zeroclaw channel doctor  # Check channel health
zeroclaw daemon          # Start runtime
bash
zeroclaw status          # 检查配置
zeroclaw doctor          # 运行诊断
zeroclaw channel doctor  # 检查渠道健康状态
zeroclaw daemon          # 启动运行时

Safe Config Change Flow

安全配置变更流程

  1. Backup 
    ~/.zeroclaw/config.toml
  2. Apply one logical change
  3. Run 
    zeroclaw doctor
  4. Restart daemon/service
  5. Verify with 
    status
    + 
    channel doctor
  1. 备份
    ~/.zeroclaw/config.toml
  2. 应用一个逻辑变更
  3. 运行
    zeroclaw doctor
  4. 重启daemon/服务
  5. 使用
    status
    + 
    channel doctor
    验证

Logs

日志位置

  • macOS/Windows: 
    ~/.zeroclaw/logs/daemon.stdout.log
    , 
    daemon.stderr.log
  • Linux systemd: 
    journalctl --user -u zeroclaw.service -f
  • macOS/Windows: 
    ~/.zeroclaw/logs/daemon.stdout.log
    , 
    daemon.stderr.log
  • Linux systemd: 
    journalctl --user -u zeroclaw.service -f

Network Deployment

网络部署

Telegram/Discord/Slack (No Port Needed)

Telegram/Discord/Slack（无需端口）

These use long-polling — outbound only. Works behind NAT, on RPi, in home labs.
bash
zeroclaw daemon --host 127.0.0.1 --port 3000
这些渠道使用长轮询 — 仅需出站连接。可在NAT后、树莓派、家庭实验室中运行。
bash
zeroclaw daemon --host 127.0.0.1 --port 3000

Webhook Channels (WhatsApp, etc.)

Webhook渠道（WhatsApp等）

Need a public URL. Options:
  • [tunnel] provider = "tailscale"
    — Tailscale Funnel
  • [tunnel] provider = "ngrok"
    — ngrok tunnel
  • Cloudflare Tunnel
需要公网URL。可选方案：
  • [tunnel] provider = "tailscale"
    — Tailscale Funnel
  • [tunnel] provider = "ngrok"
    — ngrok隧道
  • Cloudflare Tunnel

LAN Access

LAN访问

toml
[gateway]
host = "0.0.0.0"
allow_public_bind = true
toml
[gateway]
host = "0.0.0.0"
allow_public_bind = true

Hardware Peripherals

硬件外设

Supported Boards

支持的开发板

BoardTransportPath
nucleo-f401reserial/dev/ttyACM0
arduino-unoserial/dev/ttyACM0, /dev/cu.usbmodem*
arduino-uno-qbridge(IP)
rpi-gpionativenative
esp32serial/dev/ttyUSB0
开发板传输方式路径
nucleo-f401re串口/dev/ttyACM0
arduino-uno串口/dev/ttyACM0, /dev/cu.usbmodem*
arduino-uno-q桥接(IP地址)
rpi-gpio原生native
esp32串口/dev/ttyUSB0

Adding a Board

添加开发板

bash
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
Or in config:
toml
[peripherals]
enabled = true
datasheet_dir = "docs/datasheets"

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200
bash
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
或在配置文件中添加：
toml
[peripherals]
enabled = true
datasheet_dir = "docs/datasheets"

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

Two Operation Modes

两种操作模式

  1. Edge-Native: ZeroClaw runs directly on device (ESP32, RPi) with local GPIO/I2C/SPI
  2. Host-Mediated: ZeroClaw on host (Mac/Linux) connects to device via USB/J-Link for development/debugging
  1. 边缘原生： ZeroClaw直接在设备上运行（ESP32、树莓派），支持本地GPIO/I2C/SPI
  2. 主机中介： ZeroClaw在主机（Mac/Linux）上运行，通过USB/J-Link连接设备进行开发/调试

Troubleshooting Quick Reference

故障排除速查

ProblemSolution
cargo
not found
./bootstrap.sh --install-rust
zeroclaw
not found
export PATH="$HOME/.cargo/bin:$PATH"
Gateway unreachableCheck 
gateway.host
/
gateway.port
in config
Telegram 
terminated by other getUpdates
Stop extra daemon/channel processes — only one poller per token
Channel unhealthy
zeroclaw channel doctor
then verify credentials + allowlist
Service not running
zeroclaw service stop && zeroclaw service start
Config world-readable warning
chmod 600 ~/.zeroclaw/config.toml
Browser opens headless (invisible)Set 
executablePath
in 
~/.agent-browser/config.json
to real Chrome — Playwright's bundled Chromium ignores 
headed
flag
"domain not in allowed list" for browserSet 
browser.allowed_domains = ["*"]
in config + restart daemon
Agent claims domain restrictions that don't existThe LLM is hallucinating — tell it "allowed_domains is wildcard, browse it now"
agent-browser
not found
npm install -g agent-browser
问题解决方案
cargo
未找到		执行
./bootstrap.sh --install-rust
zeroclaw
未找到		执行
export PATH="$HOME/.cargo/bin:$PATH"
网关无法访问检查配置中的
gateway.host
/
gateway.port
Telegram提示
terminated by other getUpdates
停止多余的daemon/渠道进程 — 每个令牌仅允许一个轮询器
渠道状态异常执行
zeroclaw channel doctor
，然后验证凭据和白名单
服务未运行执行
zeroclaw service stop && zeroclaw service start
配置文件全局可读警告执行
chmod 600 ~/.zeroclaw/config.toml
浏览器以无头模式打开（不可见）在
~/.agent-browser/config.json
中设置
executablePath
为本地Chrome路径 — Playwright捆绑的Chromium会忽略
headed
标志
浏览器提示"domain not in allowed list"在配置中设置
browser.allowed_domains = ["*"]
并重启daemon
Agent声称存在不存在的域名限制LLM产生了幻觉 — 告知它"allowed_domains是通配符，现在可以浏览"
agent-browser
未找到		执行
npm install -g agent-browser

Diagnostic Commands

诊断命令

bash
zeroclaw --version
zeroclaw status
zeroclaw doctor
zeroclaw channel doctor
zeroclaw channel list
bash
zeroclaw --version
zeroclaw status
zeroclaw doctor
zeroclaw channel doctor
zeroclaw channel list

Workspace Files

工作区文件

FilePurpose
SOUL.md
Agent personality, identity, communication style
AGENTS.md
Session protocol, memory system, safety rules
IDENTITY.md
Name, creature type, vibe, emoji
USER.md
User profile, preferences, work context
MEMORY.md
Long-term curated memories (auto-injected in main session)
TOOLS.md
Local notes — SSH hosts, device names, environment specifics
HEARTBEAT.md
Periodic tasks (empty = skip heartbeat)
BOOTSTRAP.md
First-run onboarding (delete after initial setup)
文件用途
SOUL.md
Agent的性格、身份、沟通风格
AGENTS.md
会话协议、内存系统、安全规则
IDENTITY.md
名称、角色类型、风格、表情符号
USER.md
用户资料、偏好、工作背景
MEMORY.md
长期整理的记忆（会自动注入主会话）
TOOLS.md
本地笔记 — SSH主机、设备名称、环境细节
HEARTBEAT.md
周期性任务（空文件表示跳过心跳检查）
BOOTSTRAP.md
首次运行引导（初始设置后可删除）

Memory System

内存系统

  • Daily notes: 
    memory/YYYY-MM-DD.md
    — raw logs (on-demand via tools)
  • Long-term: 
    MEMORY.md
    — curated, auto-injected each session
  • Tools: 
    memory_store
    , 
    memory_recall
    , 
    memory_forget
  • 每日笔记： 
    memory/YYYY-MM-DD.md
    — 原始日志（可通过工具按需访问）
  • 长期记忆： 
    MEMORY.md
    — 整理后的记忆，每次会话都会自动注入
  • 工具：
    memory_store
    、
    memory_recall
    、
    memory_forget

Security Model

安全模型

  • Deny-by-default channel allowlists
  • Gateway pairing required by default
  • Public bind disabled by default
  • Workspace-scoped filesystem access
  • Command allowlist for shell execution
  • Rate limiting (actions/hour, cost/day)
  • Encrypted secrets storage
  • Pluggable sandboxing (Landlock, Firejail, Bubblewrap, Docker — feature-gated)
  • Audit logging (proposal/roadmap — HMAC-signed tamper-evident logs)
  • 默认拒绝的渠道白名单
  • 默认要求网关配对
  • 默认禁用公网绑定
  • 工作区范围的文件系统访问
  • Shell执行的命令白名单
  • 速率限制（每小时操作数、每日成本）
  • 加密密钥存储
  • 可插拔沙箱（Landlock、Firejail、Bubblewrap、Docker — 需启用对应特性）
  • 审计日志（规划中 — 基于HMAC签名的防篡改日志）

LangGraph / Python Integration

LangGraph / Python集成

zeroclaw-tools
Python package provides LangGraph-based tool calling for consistent behavior with any OpenAI-compatible provider:
bash
pip install zeroclaw-tools
python
from zeroclaw_tools import create_agent, shell, file_read, file_write
agent = create_agent(tools=[shell, file_read, file_write], model="glm-5", api_key="your-api-key", base_url="your-base-url")
zeroclaw-tools
Python包提供基于LangGraph的工具调用功能，可与任何兼容OpenAI的提供商实现一致的行为：
bash
pip install zeroclaw-tools
python
from zeroclaw_tools import create_agent, shell, file_read, file_write
agent = create_agent(tools=[shell, file_read, file_write], model="glm-5", api_key="your-api-key", base_url="your-base-url")

Open Skills Integration

Open Skills集成

ZeroClaw integrates with Open Skills (https://github.com/besoeasy/open-skills) — pre-built execution playbooks that reduce token usage by 95-98%.
Skills are synced to 
~/.zeroclaw/workspace/skills/
and installed via:
bash
zeroclaw skills install <github-url-or-local-path>
ZeroClaw支持与Open Skills（https://github.com/besoeasy/open-skills）集成 — 预构建的执行剧本可将令牌使用量减少95-98%。
技能会同步到
~/.zeroclaw/workspace/skills/
，可通过以下命令安装：
bash
zeroclaw skills install <github-url-or-local-path>

Key Design Principles

核心设计原则

  1. Zero overhead — <5MB RAM, <10ms startup, ~3.4MB binary
  2. Zero compromise — full security without sacrificing performance
  3. 100% Rust — single binary, no runtime dependencies
  4. 100% Agnostic — swap providers, channels, tools, memory, tunnels at will
  5. Trait-driven — every subsystem is a trait, making everything pluggable
  6. Secure by default — pairing, scoping, allowlists, encrypted secrets
  1. 零开销 — 内存<5MB，启动<10ms，二进制文件约3.4MB
  2. 零妥协 — 兼顾完整安全性与高性能
  3. 100% Rust实现 — 单二进制文件，无运行时依赖
  4. 100% 无绑定 — 可随意替换提供商、渠道、工具、内存、隧道
  5. Trait驱动 — 每个子系统都是Trait，所有组件均可插拔
  6. 默认安全 — 配对认证、范围限制、白名单、加密密钥