repo:nullclaw/nullclaw: Fastest, smallest, and fully autonomous AI assistant infrastructure written in Zig
NullClaw
零开销。零妥协。100% Zig 编写。100% 平台无关。 678 KB 二进制文件。约 1 MB 内存占用。启动时间 <2 毫秒。可在任何配备 CPU 的设备上运行。
特性
- 极致精简：678 KB 静态二进制文件 — 无运行时依赖、无虚拟机、无框架开销。
- 近零内存占用：峰值内存约 1 MB。可在最廉价的 ARM 单板计算机和微控制器上流畅运行。
- 瞬时启动：Apple Silicon 平台 <2 毫秒，0.8 GHz 边缘计算核心 <8 毫秒。
- 真正的可移植性：单一独立二进制文件支持 ARM、x86 和 RISC-V 架构。随处部署，即刻运行。
- 功能完备：22+ 提供商、18 种渠道、18+ 工具、混合向量+FTS5 内存、多层沙箱、隧道、硬件外设、MCP、子代理、流式传输、语音功能 — 完整技术栈。
为何选择 nullclaw
- 默认精简：Zig 编译生成超小静态二进制文件。无内存分配器开销、无垃圾回收、无运行时依赖。
- 设计安全：配对机制、严格沙箱（landlock、firejail、bubblewrap、docker）、显式允许列表、工作区范围限定、加密密钥。
- 完全可替换：核心系统基于虚函数表接口（提供商、渠道、工具、内存、隧道、外设、观察者、运行时）。
- 无锁定限制：支持 OpenAI 兼容的提供商 + 可插拔自定义端点。
基准测试快照
本地机器基准测试（macOS arm64，2026 年 2 月），已针对 0.8 GHz 边缘硬件进行标准化。
| 编程语言 | TypeScript | Python | Go | Rust | Zig |
| 内存占用 | > 1 GB | > 100 MB | < 10 MB | < 5 MB | ~1 MB |
| 启动时间（0.8 GHz） | > 500 秒 | > 30 秒 | < 1 秒 | < 10 毫秒 | < 8 毫秒 |
| 二进制文件大小 | ~28 MB（发布版） | N/A（脚本） | ~8 MB | 3.4 MB | 678 KB |
| 测试用例 | — | — | — | 1,017 | 3,230+ |
| 源文件数 | ~400+ | — | — | ~120 | ~110 |
| 硬件成本 | Mac Mini $599 | Linux 单板计算机 ~$50 | Linux 开发板 $10 | 任何 $10 硬件 | 任何 $5 硬件 |
测量使用 /usr/bin/time -l 工具，基于 ReleaseSmall 构建。nullclaw 是静态二进制文件，无任何运行时依赖。
本地复现方法：
zig build -Doptimize=ReleaseSmall
ls -lh zig-out/bin/nullclaw
/usr/bin/time -l zig-out/bin/nullclaw –help
/usr/bin/time -l zig-out/bin/nullclaw status
快速开始
前提条件： 使用 Zig 0.15.2（精确版本）。 0.16.0-dev 及其他 Zig 版本目前不受支持，可能导致构建失败。 构建前请验证：zig version 命令应输出 0.15.2。
git clone https://github.com/nullclaw/nullclaw.git
cd nullclaw
zig build -Doptimize=ReleaseSmall
# Quick setup
nullclaw onboard –api-key sk-… –provider openrouter
# Or interactive wizard
nullclaw onboard –interactive
# Chat
nullclaw agent -m "Hello, nullclaw!"
# Interactive mode
nullclaw agent
# Start gateway runtime (gateway + all configured channels/accounts + heartbeat + scheduler)
nullclaw gateway # default: 127.0.0.1:3000
nullclaw gateway –port 8080 # custom port
# Check status
nullclaw status
# Run system diagnostics
nullclaw doctor
# Check channel health
nullclaw channel status
# Start specific channels
nullclaw channel start telegram
nullclaw channel start discord
nullclaw channel start signal
# Manage background service
nullclaw service install
nullclaw service status
# Migrate memory from OpenClaw
nullclaw migrate openclaw –dry-run
nullclaw migrate openclaw
实践
下载源代码
国内直接从gitcode下载源代码
git clone https://gitcode.com/gh_mirrors/nu/nullclaw
Zig编译
cd nullclaw
zig build -Doptimize=ReleaseSmall
FreeBSD下编译失败，到Ubuntu系统编译。
测试
测试
/usr/bin/time -l zig-out/bin/nullclaw –help
我这里没有-l参数，所以这样：
/usr/bin/time zig-out/bin/nullclaw –help
nullclaw — The smallest AI assistant. Zig-powered.
USAGE:
nullclaw <command> [options]
COMMANDS:
onboard Initialize workspace and configuration
agent Start the AI agent loop
gateway Start the gateway server (HTTP/WebSocket)
service Manage OS service lifecycle (install/start/stop/restart/status/uninstall)
status Show system status
version Show CLI version
doctor Run diagnostics
cron Manage scheduled tasks
channel Manage channels (Telegram, Discord, Slack, …)
skills Manage skills
hardware Discover and manage hardware
migrate Migrate data from other agent runtimes
memory Inspect and maintain memory subsystem
workspace Maintain workspace markdown/bootstrap files
capabilities Show runtime capabilities manifest
models Manage provider model catalogs
auth Manage OAuth authentication (OpenAI Codex)
update Check for and install updates
help Show this help
OPTIONS:
onboard [–interactive] [–api-key KEY] [–provider PROV] [–memory MEM]
agent [-m MESSAGE] [-s SESSION] [–provider PROVIDER] [–model MODEL] [–temperature TEMP]
gateway [–port PORT] [–host HOST]
version | –version | -V
service <install|start|stop|restart|status|uninstall>
cron <list|add|once|remove|pause|resume> [ARGS]
channel <list|start|status|add|remove> [ARGS]
skills <list|install|remove> [ARGS]
hardware <discover|introspect|info> [ARGS]
migrate openclaw [–dry-run] [–source PATH]
memory <stats|count|reindex|search|get|list|drain-outbox|forget> [ARGS]
workspace reset-md [–dry-run] [–include-bootstrap] [–clear-memory-md]
capabilities [–json]
models refresh
auth <login|status|logout> <provider> [–import-codex]
update [–check] [–yes]
0.00user 0.00system 0:00.01elapsed 40%CPU (0avgtext+0avgdata 2460maxresident)k
0inputs+0outputs (0major+88minor)pagefaults 0swaps
快速配置
nullclaw onboard –api-key sk-… –provider openrouter
自定义provider
nullclaw的快速配置：nullclaw onboard –api-key sk-… –provider openrouter 如果不用给定的provider，用自定义的base_url，应该怎么配置？
nullclaw onboard –api-key sk-你的API密钥 –provider openrouter –base-url https://你的自定义域名/v1
# AIStudio
nullclaw onboard –api-key sk-你的API密钥 –provider aistudio –base-url "https://api-p9mak7fap5m7vd53.aistudio-app.com/v1"
没有base_url参数，可以使用交互方式
zig-out/bin/nullclaw onboard –interactive
支持这些模型：
Step 1/8: Select a provider
[1] OpenRouter (multi-provider, recommended)
[2] Anthropic (Claude direct)
[3] OpenAI (GPT direct)
[4] Google Gemini
[5] DeepSeek
[6] Groq (fast inference)
[7] Z.AI (Zhipu coding)
[8] GLM (Zhipu general)
[9] Together AI (inference)
[10] Fireworks AI (fast)
[11] Mistral
[12] xAI (Grok)
[13] Venice
[14] Moonshot (Kimi)
[15] Synthetic
[16] OpenCode Zen
[17] MiniMax
[18] Qwen (Alibaba)
[19] Cohere
[20] Perplexity
[21] NVIDIA NIM (enterprise)
[22] Cloudflare AI Gateway
[23] Vercel AI Gateway
[24] Amazon Bedrock
[25] Qianfan (Baidu)
[26] GitHub Copilot
[27] Astrai
[28] Poe
[29] Ollama (local CLI)
[30] LM Studio (local GUI)
[31] Claude CLI (claude code, local)
[32] Codex CLI (OpenAI codex, local)
没有找到自定义模型的地方。
所以，它目前不支持自定义模型….
暂时就先实践到这里吧。
调试
NullClaw build 报错：zig build -Doptimize=ReleaseSmall
install └─ install nullclaw └─ compile exe nullclaw ReleaseSmall native 1 errors /usr/local/lib/zig/std/net.zig:816:5: error: std.net.if_nametoindex unimplemented for this OS @compileError("std.net.if_nametoindex unimplemented for this OS"); ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ referenced by: resolve: /usr/local/lib/zig/std/net.zig:635:46 resolveIp6: /usr/local/lib/zig/std/net.zig:148:48 14 reference(s) hidden; use '-freference-trace=16' to see all references error: the following command failed with 1 compilation errors: /usr/local/bin/zig build-exe .zig-cache/o/4bc76c1a180d20221b7ab854d513a7a5/libsqlite3.a -fstrip -fomit-frame-pointer -fno-unwind-tables -OReleaseSmall -I .zig-cache/o/3a8809f156846b246a8b58aee0dcf73a –dep nullclaw –dep build_options -Mroot=/home/skywalk/github/nullclaw/src/main.zig .zig-cache/o/4bc76c1a180d20221b7ab854d513a7a5/libsqlite3.a .zig-cache/o/4bc76c1a180d20221b7ab854d513a7a5/libsqlite3.a -OReleaseSmall -I .zig-cache/o/3a8809f156846b246a8b58aee0dcf73a -I .zig-cache/o/3a8809f156846b246a8b58aee0dcf73a –dep build_options –dep websocket -Mnullclaw=/home/skywalk/github/nullclaw/src/root.zig -Mbuild_options=.zig-cache/c/2b1bc3d40db9b5ee4e5da17b8bc9766f/options.zig -OReleaseSmall –dep build -Mwebsocket=/home/skywalk/.cache/zig/p/websocket-0.1.0-ZPISdRlzAwBB_Bz2UMMqxYqF6YEVTIBoFsbzwPUJTHIc/src/websocket.zig -Mbuild=.zig-cache/c/9df3ebb56e512146581134c82a20886e/options.zig -lc –cache-dir .zig-cache –global-cache-dir /home/skywalk/.cache/zig –name nullclaw -dead_strip_dylibs –zig-lib-dir /usr/local/lib/zig/ –listen=-
Build Summary: 4/7 steps succeeded; 1 failed install transitive failure └─ install nullclaw transitive failure └─ compile exe nullclaw ReleaseSmall native 1 errors
error: the following build command failed with exit code 1: .zig-cache/o/f840e01eb87b4c600faeeca01d0dad25/build /usr/local/bin/zig /usr/local/lib/zig /home/skywalk/github/nullclaw .zig-cache /home/skywalk/.cache/zig –seed 0x9c47101f -Z0838c4cf25ed56a5 -Doptimize=ReleaseSmall 核心问题是这一句：
/usr/local/lib/zig/std/net.zig:816:5: error: std.net.if_nametoindex unimplemented for this OS
这个错误表明 Zig 标准库中的 std.net.if_nametoindex 函数在您的操作系统上尚未实现，导致编译失败。以下是详细分析和解决方案：
错误原因分析
if_nametoindex 未实现：
- Zig 的 std.net 模块尝试使用操作系统相关的网络接口函数 if_nametoindex（将网络接口名转换为索引）。
- 您的操作系统（从路径看可能是 Linux，但具体发行版/版本未明确）缺少该函数的实现支持。
触发路径：
- 编译过程中，Zig 尝试链接 libsqlite3 和 websocket 依赖项。
- 在解析网络相关代码时（如 IPv6 地址解析），调用了 std.net.resolve() → resolveIp6() → 最终触发 if_nametoindex。
解决方案
✅ 1. 更新 Zig 到最新版本
但是NullClaw说必须是0.15.2版本，所以这个办法不行。
换系统，从FreeBSD换成Ubuntu试试。
交互模式Configure channels
Step 7/8: Configure channels now? [Y/n]: Channel setup: [1] Telegram (not configured) [2] Discord (not configured) [3] Slack (not configured) [4] Webhook (not configured) [5] Matrix (not configured) [6] Mattermost (not configured) [7] Signal (not configured) [8] Nostr (not configured) Other channels in this build require manual config: iMessage WhatsApp IRC Lark DingTalk Email Line QQ OneBot MaixCam Web
基础选择建议 常用即时通讯渠道 如果需要接收通知，优先选择你日常使用的平台： 选1：Telegram，适合国际用户，支持群组和频道通知 选2：Discord，适合开发者社区、游戏团队等场景 选3：Slack，企业办公协作常用工具 选4：Webhook，支持自定义对接自己的服务或第三方平台 国内可用渠道 如果在国内使用，优先考虑： 6：Mattermost，开源的企业级通讯工具，适合内部团队 12：QQ，国内普及度高的即时通讯工具 13：微信（Web），适合对接企业微信或个人微信通知 二、特殊需求选择 自定义开发对接 如果需要对接自己的系统，选择4 Webhook，可以通过HTTP请求自定义通知的格式和接收地址 小众场景需求 7 Signal：注重隐私的通讯工具 8 Nostr：去中心化的社交协议 14 IRC：老牌的互联网聊天协议，适合技术社区
