Skip to content

NextClaw CLI:能力全景与命令全集

nextclaw 命令行是 NextClaw 的一等操作入口。适合结构化操作的产品能力会尽量同时通过 CLI 提供,让普通用户、高级用户、开发者、脚本、CI 和其他 Agent 可以调用同一套 NextClaw 能力。

这不意味着所有界面都要搬进终端。纯视觉、拖拽和直接操控仍然更适合图形界面;CLI 更适合启动与托管、查询与诊断、批量操作、自动化和系统集成。

本页有两个用途:

  • 按能力域查看 NextClaw 当前可以做什么;
  • 按命令路径查找完整 CLI 能力面。

命令注册树是本页的事实源。新增、删除或重命名 CLI 命令时,中英文页面必须同步更新,仓库测试会检查这里是否完整覆盖真实命令。

怎么使用这份全集

这里列出每一个可执行命令路径及其主要用途。查看某个命令的完整参数、默认值和选项时,运行:

bash
nextclaw <command> --help

查看版本使用 nextclaw --version。许多查询和管理命令支持 --json;用于脚本、CI 或 Agent 集成前,请先查看对应命令的帮助。首次安装和启动请看快速开始,日常最常用的少量命令请看核心命令

问题反馈与私密讨论

无需 GitHub 登录,详见问题反馈feedback 只表示反馈应用;通用主题、帖子、参与者和事件订阅统一由 discussion 承载。

命令用途
nextclaw feedback submit提交私密反馈并保存回执
nextclaw feedback list列出本机回执
nextclaw feedback get读取反馈详情和回复
nextclaw feedback reply补充复现信息
nextclaw feedback withdraw撤回反馈
nextclaw feedback link关联当前 NextClaw 账号
nextclaw feedback sync同步账号反馈
nextclaw feedback export导出私密回执
nextclaw feedback import恢复私密回执
nextclaw feedback workflow skill-path定位随包反馈处理 skill
nextclaw feedback workflow list查询已批准反馈工作队列
nextclaw feedback workflow get读取反馈及当前审批
nextclaw feedback workflow claim领取已批准反馈
nextclaw feedback workflow comment写入处理端回复
nextclaw feedback workflow result提交验证结果或阻塞原因
nextclaw feedback workflow triage分类,不能授予修复权限
nextclaw feedback workflow recover确认旧执行停止后恢复
nextclaw feedback workflow authorize-delivery关联获准发布的修复提交
nextclaw feedback workflow publish核验发布证明并回写
nextclaw discussion skill-path定位随包讨论参与 skill
nextclaw discussion list按空间列出可访问主题
nextclaw discussion events从游标读取面向当前角色的事件
nextclaw discussion get读取主题和有序帖子
nextclaw discussion post以认证参与者身份发帖
nextclaw discussion listen configure保存 endpoint、参与凭据和消费命令;Codex 预设可接收工作目录
nextclaw discussion listen start后台启动代码监听并完成首次扫描
nextclaw discussion listen status查看监听健康度、心跳和最近错误
nextclaw discussion listen stop停止当前监听实例
nextclaw discussion listen restart使用已保存配置重启监听
nextclaw discussion listen worker内部监听进程入口
nextclaw discussion listen codex-desktop-trigger内部 Codex Desktop 消费预设入口
nextclaw discussion listen codex-desktop-runner内部异步 Codex Desktop 任务执行入口

能力地图

能力域可以完成的事
初始化与账号初始化工作区、登录平台、查看账号与设置用户名
运行、状态与日志启停本地服务和 UI、更新、诊断、查询日志与模型用量
宿主托管安装或移除 Linux、macOS、Windows 自启动服务
远程访问启用、关闭、诊断和调试远程连接
Agent 与任务执行终端聊天、Headless 执行、Agent 与 Runtime 管理
项目与会话创建项目、管理工作项和产物关联、绑定和整理会话
自动化与学习循环管理定时任务和学习循环策略
配置与密钥读写配置、审计和应用密钥引用
MCP 与消息渠道管理 MCP 服务和消息渠道连接
Skills 与 Marketplace查看、安装、发布、更新和发现 Skills
NextClaw Apps检查、开发、打包、发布、安装、调用和管理 App 数据

初始化与账号

命令用途
nextclaw onboard初始化 NextClaw 配置和工作区
nextclaw init初始化工作区;可用 --force 覆盖模板文件
nextclaw login登录 NextClaw Platform 并保存本地凭据
nextclaw account status查看账号状态和 Marketplace 发布准备度
nextclaw account set-username设置用于个人 Marketplace 发布的用户名

运行、状态与日志

命令用途
nextclaw gateway前台启动 Gateway,可选择同时启用 UI
nextclaw ui启动 Gateway 和 UI
nextclaw start在后台启动 Gateway 和 UI
nextclaw restart受控重启服务;支持恢复的宿主就绪后续跑本次中断的会话
nextclaw serve前台运行 Gateway 和 UI,适合调试
nextclaw stop停止后台服务
nextclaw status查看当前安装形态、数据路径、运行中 Runtime 版本、进程、健康度、配置摘要和可用端点
nextclaw doctor运行诊断,并可修复安全范围内的陈旧状态
nextclaw logs path查看本地日志文件路径
nextclaw logs tail查看最近的服务或崩溃日志
nextclaw logs query按时间、级别、领域、事件和关联 ID 查询结构化日志
nextclaw usage查看最近模型用量、历史记录和缓存统计
nextclaw update检查、下载或应用 NextClaw Runtime 更新

经用户授权,AI 可通过普通命令行执行 nextclaw update,在结果要求重启时执行 nextclaw restart。支持本地运行时 API 的后台服务、前台宿主和 NextClaw systemd 服务会记录当时正在运行的会话;新进程就绪后,发起会话和并行会话各续跑一次,并收到“重启已完成、不要重放中断命令”的上下文。

自动恢复要求不带修改配置的端口、打开浏览器或超时参数。桌面和其它 supervisor 托管的退出、旧版本兼容 stop/start、崩溃及普通启动不在此恢复范围内。请求超时不代表重启失败:先用 nextclaw status --json 检查状态,不要连续重试更新或重启。其中 runtime.version 由实际提供本地 API 的进程报告,是运行中宿主的权威版本;nextclaw --version 表示本次命令选择的 CLI/Runtime 版本。已完成或普通失败的任务不会因此自动重跑。

查询当前实例的数据位置时使用 nextclaw status --jsoninstancestorage。便携版的 storage.portableDataRoot 指向 <portableRoot>/datastorage.runtimeHome 指向其中的 runtime-home;Desktop 日志与 Runtime 结构化日志分别由 desktopLogsDirectoryruntimeLogsDirectory 表示。.nextclaw 只是未覆盖时的普通默认值,不能代替当前实例查询。

宿主托管与自启动

为什么重启后能继续工作、如何授权 AI 自行维护,以及完整限制,见自我管理专题

命令用途
nextclaw service install-systemd安装 Linux 用户级或系统级 systemd 服务
nextclaw service uninstall-systemd移除 NextClaw 管理的 systemd 服务
nextclaw service install-launch-agent安装 macOS LaunchAgent
nextclaw service uninstall-launch-agent移除 macOS LaunchAgent
nextclaw service install-task安装 Windows 计划任务
nextclaw service uninstall-task移除 Windows 计划任务
nextclaw service autostart status查看宿主自启动 owner 和运行状态
nextclaw service autostart doctor诊断宿主自启动配置

远程访问

命令用途
nextclaw remote enable启用由服务托管的远程访问
nextclaw remote disable关闭远程访问
nextclaw remote status查看远程访问和连接状态
nextclaw remote doctor运行远程访问诊断
nextclaw remote connect以前台调试模式注册设备并保持连接

Agent 与任务执行

命令用途
nextclaw agent在终端交互,或通过 -m 发送一次性消息
nextclaw exec以 Headless 模式运行一次任务,支持文本、JSON 和 JSONL;详见 nextclaw exec
nextclaw agents list列出已配置的 Agent
nextclaw agents runtimes列出并可主动探测可用 Agent Runtime
nextclaw agents runtime config查看或修改指定 Runtime 的配置
nextclaw agents new创建 Agent,并设置名称、头像、主目录和 Runtime
nextclaw agents update更新现有 Agent
nextclaw agents remove删除 Agent

项目与会话

命令用途
nextclaw projects list列出所有已注册项目,包括尚无会话的项目
nextclaw projects templates列出内置项目模板
nextclaw projects create创建并注册项目
nextclaw projects register注册已有目录且不修改目录内容;可用 --name 指定项目名称
nextclaw projects remove从项目列表移除项目;保留本地目录、历史会话和项目工作记录,并要求精确项目 ID 确认
nextclaw projects work list按项目 ID 分页列出工作项;支持 --state--cursor--limit--include-deleted
nextclaw projects work get查看工作项详情
nextclaw projects work create创建持久化工作项
nextclaw projects work update更新工作项字段、状态或关注标记
nextclaw projects work delete软删除工作项
nextclaw projects work restore恢复已删除工作项
nextclaw projects work activity查看工作项的不可变活动历史
nextclaw projects work artifact link关联项目内的产物文件
nextclaw projects work artifact unlink移除产物关联
nextclaw projects work state list列出项目的自定义工作状态
nextclaw projects work state create创建工作状态
nextclaw projects work state update更新或重排工作状态
nextclaw projects work state delete删除状态并按需迁移现有工作项
nextclaw sessions rename重命名会话
nextclaw sessions set-project把会话绑定到现有项目目录
nextclaw sessions clear-project清除会话的显式项目绑定
nextclaw sessions delete永久删除会话;需 --confirm <会话 ID>

所有 projects work 命令都必须显式传入 --project <项目 ID>,并通过正在运行的本地 NextClaw 服务执行。

自动化与学习循环

命令用途
nextclaw cron list列出定时任务
nextclaw cron add添加按间隔、Cron 表达式或指定时间运行的任务
nextclaw cron remove删除定时任务
nextclaw cron enable启用定时任务
nextclaw cron disable禁用定时任务
nextclaw cron run立即运行指定任务
nextclaw learning-loop status查看学习循环设置
nextclaw learning-loop enable启用学习循环
nextclaw learning-loop disable禁用学习循环
nextclaw learning-loop threshold设置触发学习回顾的工具调用阈值

配置与密钥

供应商、模型与搜索

这些命令通过正在运行的 NextClaw 管理设置,输出 JSON。先启动 NextClaw,使用 providers templates 查看模板,再用 providers add office --type openai --api-key-env MY_PROVIDER_KEY 添加供应商;密钥从指定环境变量读取,不会输出明文密钥或自定义请求头值。

bash
nextclaw providers models discover office --json
nextclaw providers models set office <模型标> --json
nextclaw providers test office --model <模型标> --json
nextclaw models set <模型标> --json
nextclaw models show --json
nextclaw providers show office --json

发现返回上游模型名称;选择后加上供应商实例前缀,例如 office 的 gpt-example 使用 office/gpt-example,已有前缀时不重复添加,上游名称中的斜杠保留。发现只查询,不自动保存;models set(在 providers 下)替换该供应商完整模型列表,不传模型则清空。models configure 替换全部模型能力覆盖,支持重复的 --vision 模型=true|false--thinking 模型=off,high--thinking-default 模型=high,或 --clear;请先查询并包含需要保留的条目。默认思考级别必须包含在提供的支持列表中,vision=false 表示移除正向覆盖,不强制否定内置能力。

连接测试失败返回非零退出码。授权先执行 auth start,按返回的网址与代码操作,再按返回间隔执行 auth poll;pending 表示尚未完成。配置写入等待服务应用步骤返回,应用失败即使已经保存也需要排查;命令不会重启服务。

搜索示例:nextclaw search provider exa --api-key-env MY_EXA_KEY,再执行 nextclaw search configure --provider exa --enabled-provider exa --max-results 10,通过 search show 确认。结果数量支持 1–50;启用列表整体替换,--clear-enabled-providers 禁用全部。Bocha 的 summary/freshness/docs-url 和 Tavily 的 search-depth/include-answer 通过相应命令帮助查看,其他供应商不接受这些专属选项。

命令用途
nextclaw providers list查看供应商实例
nextclaw providers templates查看模板与授权方法
nextclaw providers show查看指定供应商
nextclaw providers add添加模板或自定义供应商
nextclaw providers update修改名称、地址、凭据、协议和请求头
nextclaw providers remove移除供应商及其密钥引用
nextclaw providers enable启用供应商
nextclaw providers disable停用供应商
nextclaw providers test测试模型连接
nextclaw providers models list查看已配置模型及能力覆盖
nextclaw providers models discover发现可用模型,不自动保存
nextclaw providers models set替换或清空模型列表
nextclaw providers models configure替换或清空模型能力覆盖
nextclaw providers auth start启动供应商授权
nextclaw providers auth poll查询一次授权进度
nextclaw providers auth import从支持的供应商 CLI 导入授权
nextclaw models list查看运行时模型目录
nextclaw models show查看默认模型
nextclaw models set设置默认模型
nextclaw search show查看搜索设置
nextclaw search configure选择默认、启用的搜索供应商及结果数量
nextclaw search provider配置单个搜索供应商

通用配置与密钥

供应商、模型、搜索等已覆盖任务优先使用上述命令;通用配置命令用于尚无对应命令的设置或明确的人工恢复。

命令用途
nextclaw config get按点路径读取配置值
nextclaw config set按点路径写入配置值
nextclaw config unset删除指定配置值
nextclaw secrets audit审计密钥引用的解析状态
nextclaw secrets configure配置 env、file 或 exec 密钥提供方式
nextclaw secrets apply批量或单项应用密钥引用与 provider 配置
nextclaw secrets reload通知运行中的服务重新加载密钥

MCP 与消息渠道

命令用途
nextclaw mcp list列出已配置 MCP 服务
nextclaw mcp add添加 stdio、HTTP 或 SSE MCP 服务
nextclaw mcp remove删除 MCP 服务
nextclaw mcp enable启用 MCP 服务
nextclaw mcp disable禁用 MCP 服务
nextclaw mcp doctor检查 MCP 连接与工具发现
nextclaw channels add添加或更新消息渠道配置
nextclaw channels list列出已配置渠道
nextclaw channels status查看渠道状态
nextclaw channels login通过二维码连接支持的渠道账号

Skills 与 Marketplace

| --------------------------------------- | ---------------------------------- | | nextclaw skills installed | 列出当前运行环境已安装的 Skills | | nextclaw skills info | 查看已安装 Skill 的详情 | | nextclaw skills install | 从 NextClaw Marketplace 安装 Skill | | nextclaw skills publish | 创建或发布 Marketplace Skill | | nextclaw skills update | 更新已发布的 Marketplace Skill | | nextclaw marketplace skills search | 搜索 Marketplace Skills | | nextclaw marketplace skills info | 查看 Marketplace Skill 详情 | | nextclaw marketplace skills recommend | 查看推荐 Skills | | nextclaw marketplace skills install | 安装 Marketplace Skill | | nextclaw marketplace skills update | 更新本地已安装的 Marketplace Skill |

NextClaw Apps

命令用途
nextclaw app create创建可独立构建的 App;默认生成 Rust/WASI 模板
nextclaw app doctor检查 WASI Guest 构建环境并给出修复命令
nextclaw app build构建 App 内的 Rust/WASI Service Components
nextclaw app check检查完整 App 包、Panel 或 Service 目录
nextclaw app test在隔离 Runtime 中执行 App 的 Action 冒烟测试
nextclaw app dev从完整 App 包或 Service 目录启动真实 Runtime
nextclaw app pack打包 .napp;纯 WASI App 默认生成通用产物
nextclaw app validate-publish在提交 Marketplace 前验证 App 和目标产物
nextclaw app publish向 App Marketplace 提交 App
nextclaw app call从完整 App 包或 Service 目录调用真实 Action
nextclaw app restart重启运行中 NextClaw UI 内的 Service App
nextclaw app data list列出活动和保留的 App 数据实例
nextclaw app data delete永久删除保留的 App 数据实例,需精确确认 App ID
nextclaw app marketplace search搜索官方 App Marketplace 中的 App
nextclaw app marketplace info查看 Marketplace App 和派生安装命令
nextclaw app list列出运行中 NextClaw 宿主已安装的 App
nextclaw app info查看已安装 App 的状态和版本
nextclaw app invoke通过运行中的宿主调用已启用且已安装 App 的 Action
nextclaw app verification读取运行中宿主保存的脱敏 Runtime 验证记录
nextclaw app acceptance contract读取稳定的 Portable Runtime 验收合同
nextclaw app acceptance status读取当前 Portable Runtime 验收状态与证据新鲜度
nextclaw app acceptance export以 JSON 导出合同、当前 Runtime 身份和验收状态
nextclaw app jobs list列出一个已安装 App 实例的持久化 Job
nextclaw app jobs inspect查看一个持久化 App Job
nextclaw app jobs watch从可选序号游标重放保留的 Job 进度与输出
nextclaw app jobs cancel请求取消 Job;在 Runtime 确认前仍保持等待状态
nextclaw app resident-inbox list查看持久化 Resident 事件投递状态;可用 --dead-letters 仅查看可恢复失败
nextclaw app resident-inbox replay通过宿主拥有的收件箱重放一条死信 Resident 事件
nextclaw app dependencies inspect查看外部能力/资源依赖、候选 Provider 和当前绑定
nextclaw app dependencies verify验证当前依赖是否已满足
nextclaw app dependencies setup仅在兼容 Provider 唯一时自动建立绑定
nextclaw app dependencies bind将一个依赖绑定到已安装且受信任的 Provider
nextclaw app dependencies unbind移除一个依赖绑定
nextclaw app secrets inspect查看声明的密钥槽位和非敏感 SecretRef 绑定
nextclaw app secrets verify解析绑定但绝不返回密钥值
nextclaw app secrets bind将声明的密钥槽位绑定到 env、file 或 exec Provider
nextclaw app secrets unbind移除 App SecretRef 绑定及其活动密钥权限
nextclaw app permissions inspect查看声明的目录 scope、授权状态和实际访问模式
nextclaw app permissions document grant授予或替换运行主机上的目录,可选择只读或读写
nextclaw app permissions document revoke撤销一个目录 scope,停止旧挂载并阻止后续访问
nextclaw app ai-capabilities inspect查看声明的非敏感模型和 Agent 槽位及当前绑定
nextclaw app ai-capabilities verify验证必填模型和 Agent 槽位是否就绪
nextclaw app ai-capabilities bind将声明的模型或 Agent 槽位绑定到已配置目标
nextclaw app ai-capabilities unbind移除一个模型或 Agent 槽位绑定
nextclaw app operations列出持久化的 App 生命周期操作
nextclaw app install通过运行中的 NextClaw 宿主安装 Marketplace、本地目录或 .napp App
nextclaw app enable启用已安装的 App
nextclaw app disable停用已安装的 App
nextclaw app update发起 App 后台更新
nextclaw app rollback回滚到一个已安装版本
nextclaw app uninstall发起卸载;清除数据需要精确确认 App ID

Service App 的使用方式见 Service Apps;WASM 开发命令与 Runtime 合同见 开发 WASM Service App

app devapp call 直接接受 schema v2 App 根目录。包内只有一个 Service 时会自动选择;有多个 Service 时使用 --component <service-id>。本地 .napp 可以使用相对路径安装,例如 nextclaw app install ./my-app.napp

app list --json 会列出每个 App 的 primaryPanelIdcomponents[].id。内置 show_panel_app 工具既可接收 App ID 并打开其已启用的主 Panel,也可接收具体的 Panel component ID;未知或未启用的目标会在发送 UI 展示请求前返回 PANEL_APP_NOT_FOUND

app invoke <app-id> <action-name> --input '<json>' 调用的是已启用、已安装的 App,而不是源码包;输出会带上调用 ID、追踪 ID、数据版本和验证记录 ID。使用 app verification [--acceptance <id>] [--app <id>] [--limit <n>] 可查看对应的脱敏、持久化 Runtime 事实;脚本可加 --json 获取机器可读输出。

app acceptance contract|status|export 读取产品、Server、CLI 与发布门共同使用的唯一 Portable Runtime 验收合同。status 会用当前产品版本、Runtime 版本、runner 指纹与合同指纹重新判断证据;只有 current-passed 才代表证据仍然当前有效。export 始终输出完整的机器可读状态文档。英文展示使用 --locale en;只有检查非默认验收 App 时才传 --app <id>

声明了密钥槽位的 App,可先用 app secrets inspect <app-id> 查看需要的配置;该命令不会返回密钥值。用 app secrets bind <app-id> --slot <slot> --source env|file|exec --id <secret-id> [--provider <provider>] 绑定已声明槽位,再运行 app secrets verify <app-id>。必填槽位未绑定或无法解析时,App 会显示为 needs-configuration,启用会返回 SECRET_* 错误码。app secrets unbind 会移除活动密钥权限;即使保留 App 数据,也绝不保留 Secret 绑定。

声明了目录 scope 的 App 不会在安装时自动获得文件权限。用 app permissions inspect <app-id> 查看状态;用 app permissions document grant <app-id> --scope <scope-id> --path <directory> --mode read|read-write 授予或替换运行主机目录;用 app permissions document revoke <app-id> --scope <scope-id> 撤销。实际模式不能超过 App 声明的上限,授权变化会立即淘汰旧的 Runtime 挂载。

自动化使用建议

  • 查询或管理命令支持 --json 时,脚本和 Agent 应优先使用机器可读输出。
  • 非交互任务使用 nextclaw exec --format text|json|jsonl,并根据退出码判断结果。
  • 变更配置、密钥、宿主服务和永久删除数据前,先查看该命令的 --help 和权限边界。
  • CLI、UI 和内置 AI 工具应调用同一个产品 owner;如果同一能力在多个入口行为不一致,请提交问题。

相关文档

资源协议

Command说明
nextclaw resources list发现运行中服务注册的资源分类,支持 --type、--query、--limit,输出 JSON
nextclaw resources resolve解析真实对象 URI 为不可变资产快照引用,不执行对象内容

外部协作

安装、唤醒和连续会话见外部协作。需要 Node.js 22.13+。

CommandPurpose
nextclaw collaboration connectAdd a platform connection using existing local login
nextclaw collaboration presentationConfigure caller-owned reply presentation
nextclaw collaboration webhookConfigure GitHub webhook relay or restore polling
nextclaw collaboration install-adapterRegister an explicitly installed trusted adapter module
nextclaw collaboration adaptersList builtin and explicitly installed source adapters
nextclaw collaboration trustTrust a peer agent identity on a specific platform account
nextclaw collaboration migrate-discussionImport stopped official listener bindings and checkpoint without replay
nextclaw collaboration bindExplicitly repair a binding using an existing idle Codex task
nextclaw collaboration reconcileRecheck unknown executions without resubmitting work
nextclaw collaboration retry-runExplicitly retry failed/cancelled work after inspecting side effects
nextclaw collaboration statusShow connections, tasks and runtime without starting a model
nextclaw collaboration checkCheck configured source authentication and identity
nextclaw collaboration showInspect a task, its results and delivery failures
nextclaw collaboration ingestDurably accept a CloudEvent from a trusted local producer
nextclaw collaboration serve-eventsServe authenticated protocol events (optional; platform polling needs no server)
nextclaw collaboration resolve-outputReconcile uncertain delivery; retry or discard only after manual verification
nextclaw collaboration followExplicitly invite this agent to an existing source object
nextclaw collaboration runRun the local host in the foreground
nextclaw collaboration startStart the local host in the background
nextclaw collaboration stopStop this host; preserve bindings and recoverable work
nextclaw collaboration restartRestart the shared host after confirmed shutdown
nextclaw collaboration controlQueue status, pause, resume or cancel for a context key

基于 MIT License 发布。