本页聚焦日常操作、服务化运行和常见故障排查。

• 这页适合谁：已经完成安装与基础配置，准备日常使用、服务化运行或排障的人。
• 看完去哪里：命令细节继续看 命令参考；要核对配置字段看 配置指南；涉及 webhook 与对外接入看 Gateway API。
• 如果你是从某页来的：从 安装指南 来，这页就是首次跑通的下一站；从 配置指南 来，这页用来验证配置是否真能工作；从 Gateway API 来，可回到这里看长期运行与排障顺序。

1. 执行初始化：

nullclaw onboard --interactive

2. 发送一条测试消息：

nullclaw agent -m "你好，nullclaw"

3. 启动长期运行网关：

nullclaw gateway

建议在长期运行场景使用 service 子命令：

• macOS 走 launchctl。
• Linux 环境会优先使用 systemd --user，在检测到 OpenRC 或 SysVinit 运行环境时自动切换到对应实现。
• Windows 走 Service Control Manager。
• 如果 Linux 上既没有可用的 systemd --user，也缺少必需的 OpenRC / SysVinit 支持，这组子命令会失败；此时应改用前台 nullclaw gateway 或其他外部 supervisor。

nullclaw service install
nullclaw service start
nullclaw service status

如果配置改动较大，建议重启服务：

nullclaw service stop
nullclaw service start

• 默认网关地址：127.0.0.1:3000
• 推荐保持 gateway.require_pairing = true
• 建议通过 tunnel 暴露外网访问，不直接公网监听网关
• /pair 仅支持 POST，并使用 X-Pairing-Code；多次错误尝试会触发限流，且可能进入临时锁定

网关健康检查：

curl http://127.0.0.1:3000/health

处理步骤：

1. 先跑 nullclaw doctor 看具体报错。
2. 对照 config.example.json 检查字段拼写与层级。
3. 检查 JSON 语法（逗号、引号、括号）。

常见原因：

• API Key 无效或过期。
• provider 写错（例如填了 openrouter 但 key 属于其他平台）。
• 模型路由字符串不匹配 provider。

建议排查：

nullclaw status

并重新执行：

nullclaw onboard --interactive

重点检查：

• channels.<name>.accounts.* 的 token / webhook / account 字段是否正确。
• 是否存在渠道级 allowlist / gating 配置不匹配（如 allow_from、group_allow_from、require_mention 等）。空 allow_from 不是通用的“拒绝所有”开关。
• nullclaw channel status 是否有 unhealthy 标记。
• 如果是 DingTalk，进一步看 DingTalk 运维就绪。

常见原因：

• 仍绑定在 127.0.0.1。
• 未配置 tunnel 或反向代理。
• 防火墙未放行端口。

常见原因：

• 额度较低的 coding plan 往往扛不住 tool-heavy 的 agent 回合，即使普通聊天还看起来能用。
• 当前 provider 计划对重试频率很敏感。
• 主 provider 被限流后，没有配置可切换的 fallback。

建议排查：

• 前台运行时先用 nullclaw agent --verbose。
• service 模式下查看 ~/.nullclaw/logs/daemon.stdout.log 与 ~/.nullclaw/logs/daemon.stderr.log。
• 跑一次 nullclaw status，确认当前实际使用的 provider / model。

如果 plan 本身可用但限流很严，建议保守调整 reliability：

{
  "reliability": {
    "provider_retries": 1,
    "provider_backoff_ms": 3000,
    "fallback_providers": ["openrouter"]
  }
}

如果同一 provider 有多把 key，可以配置 reliability.api_keys 让 NullClaw 在限流时轮转。

这通常意味着：

• NullClaw 里的规范工具名其实是 schedule。
• 某些通过 Ollama 提供的本地模型会输出 scheduler_tool 或 schedule_tool。
• 新版 NullClaw 会在分发前把这些 Ollama 别名规范化回 schedule。

建议检查：

• 确认当前运行的版本已经包含 Ollama 工具别名规范化修复。
• 如果仍然看到 scheduler 相关名字触发 Unknown tool，用 nullclaw agent --verbose 复现一次。
• 如果还在使用旧二进制，先升级再排查 scheduler 配置；大多数情况下问题是工具名漂移，不是 scheduler 没开。

每次改配置后，建议按顺序执行：

nullclaw doctor
nullclaw status
nullclaw channel status
nullclaw agent -m "self-check"

对 gateway 场景，额外验证：

nullclaw gateway
curl http://127.0.0.1:3000/health

• 要细查具体 CLI 行为：继续看 命令参考，按子命令逐项核对。
• 要排查配置或调整 provider/channel：继续看 配置指南。
• 要把网关开放给外部系统：继续看 Gateway API 和 安全机制。

• 安装指南
• 配置指南
• 命令参考
• Gateway API