nullclaw

Zig 写的超轻量自主 AI 助手，启动快、占用小

开源 unknown 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 8130

维护状态较活跃

是否开源是

定价模式 unknown

项目预览

项目数据

分类智能体

开发团队nullclaw

所属国家

官网地址https://nullclaw.io

GitHubhttps://github.com/nullclaw/nullclaw

定价模式unknown

价格说明定价信息待确认

访问状态

是否开源是

开源协议MIT

主要语言Zig

技术栈/模型ai,assistant,personal,zig

GitHub 星标★ 8130

30天Star增速

HF 下载量

上线时间2026-02-16 00:00:00

代码更新—

仓库体积—

本站数据更新—

维护状态较活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-10-17

浏览次数0

项目介绍

nullclaw 是一个用 Zig 语言从零编写的全自主 AI 助手基础设施，目标是在极小的资源占用下提供最快的运行速度。它解决的是现有 AI 助手框架普遍依赖 Python/Node.js 等重型运行时、启动慢、内存占用高、部署链路长的问题。核心能力包括：完全自主的任务执行循环（理解指令、规划步骤、调用工具、观察结果并迭代），轻量级 Agent 运行时，以及对本地模型和远程 API 的对接能力。项目强调“最快、最小、完全自主”三个特性，适合对延迟和资源敏感的部署环境，例如边缘设备、嵌入式场景或需要快速冷启动的服务。Zig 的编译期优化和无 GC 特性让它在启动时间和常驻内存上具备明显优势，同时单二进制分发也简化了运维。项目目前处于成长阶段，社区关注度上升较快，适合愿意尝鲜并参与共建的开发者。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

正在加载星标数据…

技术标签

使用教程

—

难度：入门约 10 分钟部署方式：本地安装 7 步

环境要求

macOS 或 Linux，安装 Homebrew（最简单路径提供免运行时依赖的预编译二进制）
任意带 CPU 的设备即可运行（二进制约 678 KB，常驻内存约 1 MB）
若走容器路线：需要 Docker、Docker Compose 和 make（仓库自带 Makefile 封装）
一个模型服务商的 API Key（示例使用 openrouter）
（可选）Nostr 频道需要安装 nak 并确保在 $PATH 中

安装与启动步骤

1安装 nullclaw

用 Homebrew 安装官方提供的即用二进制，无需额外运行时依赖。这是 README 推荐的最简路径。
```
brew install nullclaw
```
2确认可执行

查看帮助信息，确认二进制已正确安装且可被调用。
```
nullclaw --help
```
3初始化配置

运行 onboard 生成配置并选择模型服务商，API Key 用真实值替换示例中的 sk-xxxxxxxx。
```
nullclaw onboard --api-key sk-xxxxxxxx --provider openrouter
```
4启动网关运行时

启动 gateway，会同时拉起已配置的频道/账号、heartbeat 与调度器，默认监听 127.0.0.1:3000。
```
nullclaw gateway
```
5运行系统诊断

执行 doctor 检查运行环境与配置是否正常，排查启动失败原因。
```
nullclaw doctor
```
6Docker Compose 部署

进入仓库后依次构建镜像、在容器内交互式初始化配置、启动服务。
```
make build
make config
make up
```
7健康检查

Compose 网关默认端口 3210 并映射到宿主机 localhost，用 curl 检查健康端点。
```
curl http://127.0.0.1:3210/health
```

关键配置

配置项	必填	说明	示例
`models.providers.openrouter.api_key`	是	模型服务商的 API Key，配置文件中存放，勿写进命令行参数	`sk-or-...`
`agents.defaults.model.primary`	是	默认使用的主模型标识，格式为提供商/模型名	`openrouter/anthropic/claude-sonnet-4`
`gateway.port`	否	网关监听端口	`3000`
`gateway.require_pairing`	否	是否要求配对后才能访问网关	`true`
`channels.telegram.accounts.main.bot_toke`	否	Telegram 频道机器人 Token，按需配置	`123:ABC`
`autonomy.level`	否	自主执行级别，控制 Agent 的行为边界	`supervised`

如何确认成功

nullclaw gateway 输出监听信息表示启动成功（默认 127.0.0.1:3000）；Docker Compose 方式执行 curl http://127.0.0.1:3210/health 有健康响应。

常见问题

Q：API Key 能直接写在 make config 的参数里吗？

A：不能。CONFIG_ARGS 只传非敏感参数（如 --provider openrouter），密钥写在命令行会暴露在 shell 历史和进程列表中，应通过 onboard 交互式输入或写入配置文件。

Q：配置文件在哪里？怎么改？

A：默认位于 ~/.nullclaw/config.json，由 onboard 命令创建。结构与 OpenClaw 兼容（snake_case），服务商在 models.providers 下，默认模型在 agents.defaults.model.primary 下。

Q：端口被占用怎么办？

A：网关可用 nullclaw gateway --port 8080 指定端口；Docker Compose 方式可用 make up NULLCLAW_PORT=8080 覆盖端口，或用 NULLCLAW_BIND 覆盖绑定地址。

Q：没有 Homebrew 或不想装二进制怎么办？

A：可以改用仓库自带的 Docker Compose 路径，执行 make build、make config、make up 完成容器化部署。

Q：Nostr 频道需要什么前置条件？

A：需要安装 nak 并确保它在 $PATH 中；随后可在 nullclaw onboard --interactive 的第 7 步配置，或手动修改配置文件。

注意事项

不要把 API Key、机器人 Token 放进 CONFIG_ARGS，命令行参数会出现在 shell 历史和进程列表里。
只有在可信网络中、并已配置配对、webhook 密钥、白名单和主机防火墙规则时，才设置 NULLCLAW_BIND=0.0.0.0。
配置不支持顶层 default_provider / default_model 键，必须使用 models.providers 和 agents.defaults.model.primary。
Vertex 使用服务账号 JSON 模式时，需要 $PATH 中有 openssl 用于 RS256 JWT 签名。

核心亮点

用 Zig 实现，编译为单个原生二进制，无运行时依赖，冷启动和内存占用显著低于 Python/Node 方案
内置完全自主的 Agent 循环，可自主规划、调用工具并根据结果迭代，而非仅做单轮问答
代码体量小、结构清晰，便于审计和二次开发，适合嵌入到资源受限环境

不足之处

Zig 生态相对小众，第三方库和现成插件远少于 Python/JS 生态，扩展工具有限
项目处于早期成长阶段，文档和示例可能不够完善，生产环境稳定性有待验证

适用场景

在边缘设备或嵌入式硬件上部署本地 AI 助手，要求低内存和快速启动
作为 CLI 工具集成到开发工作流，自动执行文件操作、命令调用等任务
需要单二进制分发、避免复杂依赖安装的私有化 AI 助手部署场景

替代项目

OpenHands、AutoGPT

上一篇：context-infrastructure

下一篇：zeroclaw