命令参考

June 9, 2026 · View on GitHub

本页按使用场景整理 NullClaw CLI，目标是让你先找到正确命令，再去看更细的输出。

nullclaw help 提供的是顶层摘要；本页与其保持对齐，并继续展开到子命令与注意事项。

页面导航

  • 这页适合谁：已经准备使用 CLI，但还不确定命令名、子命令或常见入口的人。
  • 看完去哪里：首次配置看 配置指南；日常运行和排障看 使用与运维；如果你在改 CLI 或文档，去 开发指南。
  • 如果你是从某页来的：从 README 来，可先看“先看这几条”；从 安装指南 来，通常下一步是 onboard、agent 和 gateway；从 开发指南 来，请把本页当作 CLI 行为和示例索引。

先看这几条

  • 看总帮助：nullclaw help
  • 看版本：nullclaw version 或 nullclaw --version
  • 首次初始化：nullclaw onboard --interactive
  • 单条对话验证：nullclaw agent -m "hello"
  • 长期运行：nullclaw gateway

初始化与交互

命令说明
nullclaw help显示顶层帮助
nullclaw version / nullclaw --version查看 CLI 版本
nullclaw onboard --interactive交互式初始化配置
nullclaw onboard --api-key sk-... --provider openrouter快速写入 provider 与 API Key
nullclaw onboard --api-key ... --provider ... --model ... --memory ...一次性指定 provider、model、memory backend
nullclaw onboard --channels-only只重配 channel / allowlist
nullclaw agent -m "..."单条消息模式
nullclaw agent --workspace /path/to/workspace -m "..."本次进程使用指定 workspace 运行 agent
nullclaw agent --skill news-digest -m "..."在指定 skill 激活的状态下执行单条消息
nullclaw agent交互会话模式
nullclaw acp启动面向 ACP 兼容编辑器的 stdio 适配器
nullclaw acp --provider openai --model gpt-5.2为编辑器启动的 ACP 会话固定 provider/model

交互式模型路由

  • 在 nullclaw agent 里，/model 会显示当前模型以及已配置的路由/回退状态。
  • /config reload 会热重载 config.json 中支持的配置项（包括 Agent Profile 的更新）。
  • 如果配置了自动路由，/model 还会显示最近一次自动路由决策以及选择原因。
  • 如果某条自动路由命中的提供方暂时被限流或额度耗尽，/model 会把这条路线标成 degraded，直到冷却结束。
  • /model 还会列出已配置的自动路由及其 cost_class、quota_class 元数据。
  • /model <provider/model> 会把当前会话 pin 到该模型，并关闭自动路由。
  • /model auto 会清除这个用户 pin，把会话恢复到配置里的默认模型，并让后续回合重新使用 model_routes。
  • 如果没有配置 model_routes，/model auto 仍然会清除 pin，并把会话切回配置里的默认模型。
  • 通过 --model 或 --provider 启动 nullclaw agent 时，也会把该次运行 pin 到显式模型，从而绕过 model_routes。
  • 通过 --skill <name> 启动 nullclaw agent 时，会在第一条消息或 REPL 轮次前激活该 skill。
  • nullclaw acp 通过 stdio 使用按行分隔的 JSON-RPC。编辑器创建 ACP 会话时传入绝对 cwd；NullClaw 会把它作为 agent invoke 的 workspace。

运行与运维

命令说明
nullclaw gateway启动长期运行 runtime，默认读取配置中的 host/port
nullclaw gateway --port 8080用 CLI 覆盖网关端口
nullclaw gateway --host 0.0.0.0 --port 8080用 CLI 覆盖监听地址与端口
nullclaw gateway --workspace /path/to/workspace本次 gateway 进程使用指定 workspace
nullclaw service install安装后台服务
nullclaw service start启动后台服务
nullclaw service stop停止后台服务
nullclaw service restart重启后台服务
nullclaw service status查看后台服务状态
nullclaw service uninstall卸载后台服务
nullclaw status [--json]查看全局状态总览，或输出 machine-readable runtime snapshot
nullclaw doctor执行系统诊断
nullclaw update --check仅检查是否有更新
nullclaw update --yes自动确认并安装更新
nullclaw auth login openai-codex为 openai-codex 做 OAuth 登录
nullclaw auth login openai-codex --import-codex从 ~/.codex/auth.json 导入登录态
nullclaw auth status openai-codex查看认证状态
nullclaw auth logout openai-codex删除本地认证信息

说明：

  • auth 目前只支持 openai-codex。
  • gateway 只是覆盖 host/port，其他安全策略仍以配置文件为准。
  • agent --workspace 和 gateway --workspace 只覆盖当前进程解析到的 workspace，效果等同于设置 NULLCLAW_WORKSPACE。

渠道、任务与扩展

Channel

命令说明
nullclaw channel list [--json]列出已知 / 已配置渠道
nullclaw channel start启动默认可用渠道
nullclaw channel start telegram启动指定渠道
nullclaw channel status查看渠道健康状态
nullclaw channel info <type> [--json]查看某类渠道的已配置账号
nullclaw channel add <type>提示如何往配置里添加某类渠道
nullclaw channel remove <name>提示如何从配置里移除渠道

Cron

命令说明
nullclaw cron list [--json]查看所有计划任务
nullclaw cron status [--json]查看 scheduler 层状态与任务计数
nullclaw cron add "0 * * * *" "command"新增周期性 shell 任务
nullclaw cron add-agent "0 * * * *" "prompt" --model <model> [--announce] [--channel <name>] [--account <id>] [--to <id>]新增周期性 agent 任务
nullclaw cron once 10m "command"新增一次性延迟任务
nullclaw cron once-agent 10m "prompt" --model <model>新增一次性 agent 延迟任务
nullclaw cron run <id>立即执行指定任务
nullclaw cron pause <id> / resume <id>暂停 / 恢复任务
nullclaw cron remove <id>删除任务
nullclaw cron runs <id>查看任务最近执行记录
nullclaw cron update <id> --expression ... --command ... --prompt ... --model ... --enable/--disable更新已有任务

Skills

命令说明
nullclaw skills list列出已安装 skill
nullclaw skills install <source>从 Git URL、本地路径或 HTTPS well-known skill 端点安装 skill
nullclaw skills install --name <query>在 skill registry 中搜索并安装最匹配的 skill
nullclaw skills remove <name>移除 skill
nullclaw skills info <name>查看 skill 元信息

History

命令说明
nullclaw history list [--limit N] [--offset N] [--json]列出会话记录
nullclaw history show <session_id> [--limit N] [--offset N] [--json]查看指定会话的消息详情

数据、模型与工作区

Memory

命令说明
nullclaw memory stats查看当前 memory 配置与关键计数
nullclaw memory count查看总条目数
nullclaw memory reindex重建向量索引
nullclaw memory search "query" --limit 10执行检索
nullclaw memory get <key>查看单条 memory
nullclaw memory list --category task --limit 20按分类列出 memory
nullclaw memory drain-outbox清空 durable vector outbox 队列
nullclaw memory forget <key>删除一条 memory

Workspace / Capabilities / Models / Migrate

命令说明
nullclaw workspace edit AGENTS.md用 $EDITOR 打开 bootstrap 文件
nullclaw workspace reset-md --dry-run预览将要重置的 markdown prompt 文件
nullclaw workspace reset-md --include-bootstrap --clear-memory-md重置 bundled markdown，并可附带清理 bootstrap / memory 文件
nullclaw workspace audit扫描工作区文件，检测潜在的密钥泄漏（已知 token 前缀、PEM 块、URL 中嵌入的凭据、高熵字符串）
nullclaw workspace audit --staged | --commit <sha> | --range a..b仅扫描已暂存 diff、单个历史提交，或某个 git 修订区间
nullclaw workspace audit --json [--only-secrets] [--fail-on <level>]输出机器可读 JSON，达到阈值时返回非零退出码，便于 CI 集成
nullclaw workspace audit --llm-triage external通过 workspace_audit.llm_triage 或已配置的 primary LLM provider 使用隐私安全 envelope 重新分类（原始密钥值不离开本机）
nullclaw workspace audit --llm-provider ollama --llm-model qwen2.5-coder:7b --llm-max-calls 20为单次运行覆盖 audit triage 的 provider、model 和外部调用预算
nullclaw workspace audit --llm-triage dry-run仅打印将要发送的 envelope，不调用 LLM
nullclaw capabilities输出运行时能力摘要
nullclaw capabilities --json输出 JSON manifest
nullclaw config show [--json]输出完整的磁盘配置
nullclaw config get <path> [--json]读取一条 dotted config 值
nullclaw models list列出 provider 与默认模型
nullclaw models info <model>查看模型说明
nullclaw models summary [--json]输出供集成侧使用的 provider/key-safe 管理摘要
nullclaw models benchmark运行模型延迟基准
nullclaw models refresh刷新模型目录
nullclaw migrate openclaw --dry-run预演迁移 OpenClaw
nullclaw migrate openclaw --source /path/to/workspace指定源工作区路径迁移

说明：

  • workspace edit 只适用于 file-based backend（如 markdown、hybrid）。
  • 如果当前 memory backend 把 bootstrap 数据放在数据库里，CLI 会提示改用 agent 的 memory_store 工具，或切回 file-based backend。
  • 这些带 --json 的 read-side 命令主要用于自动化集成，以及 NullHub 对 managed instance 的 admin API 边界。

硬件与自动化集成

命令说明
nullclaw hardware scan扫描已连接硬件
nullclaw hardware flash <firmware_file> [--target <board>]烧录固件（当前输出提示，尚未完整实现）
nullclaw hardware monitor监控硬件（当前输出提示，尚未完整实现）

顶层 machine-facing flags

这组入口更偏自动化、集成、探针，不是普通用户的第一阅读路径：

命令说明
nullclaw --export-manifest导出 manifest
nullclaw --list-models --provider <name> [--api-key <key>] [--base-url <url>]列出模型信息，也支持自定义 OpenAI 兼容端点
nullclaw --probe-provider-health探测 provider 健康状态
nullclaw --probe-channel-health探测 channel 健康状态
nullclaw --from-json从 JSON 输入执行特定流程

推荐的日常排查顺序

  1. nullclaw doctor
  2. nullclaw status
  3. nullclaw channel status
  4. nullclaw agent -m "self-check"
  5. 如涉及网关，再执行 curl http://127.0.0.1:3000/health

下一步

相关页面