2. 快速初始化

# 方式一：快速设置（推荐）
nullclaw onboard --api-key sk-你的密钥 --provider openrouter

# 方式二：交互式向导
nullclaw onboard --interactive

# 方式三：仅配置频道
nullclaw onboard --channels-only

基础使用

对话模式

# 单次对话模式
nullclaw agent -m "你好，NullClaw！"

# 交互式聊天模式
nullclaw agent

系统管理

# 查看系统状态
nullclaw status

# 系统诊断
nullclaw doctor

# 查看版本
nullclaw --version

网关/守护进程模式

启动网关

# 启动网关服务（默认 127.0.0.1:3000）
nullclaw gateway

# 自定义端口
nullclaw gateway --port 8080

启动守护进程

# 启动守护进程（包含网关+所有频道+定时任务）
nullclaw daemon

# 等同于
nullclaw service start

频道管理

# 检查频道健康
nullclaw channel doctor

# 启动特定频道
nullclaw channel start telegram
nullclaw channel start discord
nullclaw channel start signal
nullclaw channel start slack
nullclaw channel start whatsapp
nullclaw channel start line
nullclaw channel start qq
nullclaw channel start matrix
nullclaw channel start irc

定时任务管理

# 列出所有定时任务
nullclaw cron list

# 添加定时任务
nullclaw cron add "0 9 * * *" "早安问候"

# 暂停/恢复任务
nullclaw cron pause <任务ID>
nullclaw cron resume <任务ID>

# 移除任务
nullclaw cron remove <任务ID>

# 立即运行任务
nullclaw cron run <任务ID>

技能包管理

# 列出已安装技能
nullclaw skills list

# 安装技能
nullclaw skills install <技能名>

# 移除技能
nullclaw skills remove <技能名>

# 查看技能信息
nullclaw skills info <技能名>

硬件设备管理

# 扫描硬件设备
nullclaw hardware scan

# 刷写固件
nullclaw hardware flash

# 监控设备
nullclaw hardware monitor

模型管理

# 列出可用模型
nullclaw models list

# 查看模型信息
nullclaw models info <模型名>

# 模型性能测试
nullclaw models benchmark

服务管理（Windows）

# 安装为系统服务
nullclaw service install

# 启动/停止/状态
nullclaw service start
nullclaw service stop
nullclaw service status

# 卸载服务
nullclaw service uninstall

网关 API

启动网关后可用的 HTTP 端点：

端点 方法 说明
/health GET 健康检查（无需认证）
/pair POST 使用配对码换取访问令牌
/webhook POST 发送消息（需要 Bearer Token）
/whatsapp GET Meta webhook 验证
/whatsapp POST WhatsApp 消息接收

API 使用示例

# 健康检查
curl http://127.0.0.1:3000/health

# 配对获取令牌
curl -X POST http://127.0.0.1:3000/pair \
  -H "X-Pairing-Code: 123456"

# 发送消息
curl -X POST http://127.0.0.1:3000/webhook \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "你好"}'

配置文件

配置文件位置

  • Windows: C:\Users\<用户名>\.nullclaw\config.json
  • Linux/macOS: ~/.nullclaw/config.json

配置示例

{
  "default_provider": "openrouter",
  "default_temperature": 0.7,

  "models": {
    "providers": {
      "openrouter": { "api_key": "sk-or-..." },
      "groq": { "api_key": "gsk_..." },
      "anthropic": { "api_key": "sk-ant-..." }
    }
  },

  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4" },
      "heartbeat": { "every": "30m" }
    }
  },

  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "123:ABC",
          "allow_from": ["user1"],
          "reply_in_private": true
        }
      }
    }
  },

  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "vector_weight": 0.7,
    "keyword_weight": 0.3
  },

  "gateway": {
    "port": 3000,
    "require_pairing": true,
    "allow_public_bind": false
  }
}

支持的 AI 服务商

服务商 说明
OpenRouter 聚合多个 AI 模型
Anthropic Claude 系列
OpenAI GPT 系列
Groq 高速推理
Ollama 本地模型
Venice 隐私优先
xAI Grok 系列
DeepSeek 深度求索
Together AI 开源模型聚合
Fireworks 高性能推理
Perplexity 搜索增强
Cohere 企业级 AI
Bedrock AWS 托管

支持的消息频道

频道 类型
CLI 命令行交互
Telegram 即时通讯
Signal 加密通讯
Discord 游戏社区
Slack 企业协作
WhatsApp 即时通讯
Line 日韩流行
Lark/Feishu 飞书
OneBot 通用机器人协议
QQ 腾讯 QQ
Matrix 去中心化通讯
IRC 老牌聊天室
Email 邮件
DingTalk 钉钉
MaixCam AI 摄像头
Webhook 自定义集成

数据迁移

从 OpenClaw 迁移数据：

# 干运行（不执行实际迁移）
nullclaw migrate openclaw --dry-run

# 执行迁移
nullclaw migrate openclaw

# 指定源路径
nullclaw migrate openclaw --source /path/to/openclaw/workspace

系统要求

  • Zig 版本: 0.15.2（精确版本）
  • 操作系统: Windows, Linux, macOS
  • 架构: x86_64, ARM64, RISC-V
  • 内存: ~1 MB RAM
  • 启动时间: <2 ms

项目特性

  • 超小体积: 678 KB 静态二进制文件
  • 极低内存: ~1 MB 峰值内存占用
  • 即时启动: <2 ms 启动时间
  • 完全便携: 单一可执行文件，无需依赖
  • 功能完整: 22+ 提供商, 17 频道, 18+ 工具
  • 安全设计: 配对认证, 沙箱隔离, 加密集

故障排查

# 运行系统诊断
nullclaw doctor

# 检查频道健康
nullclaw channel doctor

# 查看详细日志
nullclaw daemon --verbose