使用与运维

April 17, 2026 · View on GitHub

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

页面导航

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

首次启动流程

  1. 执行初始化：
nullclaw onboard --interactive
  1. 发送一条测试消息：
nullclaw agent -m "你好，nullclaw"
  1. 启动长期运行网关：
nullclaw gateway

常用命令速查

命令用途
nullclaw onboard --api-key sk-... --provider openrouter快速写入 provider 与 API Key
nullclaw onboard --interactive交互式完整初始化
nullclaw onboard --channels-only只重配 channel / allowlist
nullclaw agent -m "..."单条消息模式
nullclaw agent交互会话模式
nullclaw gateway启动长期运行 runtime（默认 127.0.0.1:3000）
nullclaw service install安装后台服务
nullclaw service start启动后台服务
nullclaw service status查看后台服务状态
nullclaw service stop停止后台服务
nullclaw service uninstall卸载后台服务
nullclaw doctor系统诊断
nullclaw status全局状态
nullclaw channel status渠道健康状态
nullclaw channel start telegram启动指定渠道
nullclaw migrate openclaw --dry-run预演迁移 OpenClaw 数据
nullclaw migrate openclaw执行迁移
nullclaw history list [--limit N] [--offset N] [--json]列出会话记录
nullclaw history show <session_id> [--limit N] [--offset N] [--json]查看指定会话的消息详情

服务化运行建议

建议在长期运行场景使用 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

高级 secrets 注入方式：

  • 生成的 service 启动器在执行 nullclaw gateway 之前，也会检查一个可执行的 ~/.nullclaw/service-env 辅助脚本。
  • 可以把 dotenvx、sops 或其他本地 secret loader 放进这个脚本里，而不需要手动修改已安装的 service unit / 脚本。

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

nullclaw service stop
nullclaw service start

网关与配对（Pairing）

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

网关健康检查：

curl http://127.0.0.1:3000/health

常见问题（FAQ）

1) 启动失败，提示配置错误

处理步骤：

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

2) 模型调用失败（401/403）

常见原因：

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

建议排查：

nullclaw status

并重新执行：

nullclaw onboard --interactive

3) 收不到渠道消息

重点检查：

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

4) 网关启动但外部不可访问

常见原因：

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

5) provider 返回 429 / “rate limit exceeded”

常见原因：

  • 额度较低的 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 在限流时轮转。

6) 本地 Ollama 模型提示没有 scheduler_tool 权限

这通常意味着：

  • 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

下一步

相关页面