nuwa-cli

English | 简体中文

Headless multi-engine agent CLI. nuwa-cli bundles ACP runtimes for Codex and Claude. A locally installed CLI is optional: when present, nuwa-cli reuses its ~/.claude / ~/.codex history and configuration; otherwise the session can run entirely from model, environment, and MCP configuration delivered over ACP.

One-line installer (S3 mirror, CN-reachable, auto-configures PATH):

# Windows (PowerShell)
irm https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/install-from-s3.ps1 | iex

# macOS / Linux
curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/install-from-s3.sh | bash

Or via npm (requires Node.js 22+):

npm install -g @nuwax-ai/nuwa-cli@beta --progress=true
nuwa-cli doctor

npm too slow? NUWACLI_REGISTRY=https://registry.npmmirror.com (bash) / $env:NUWACLI_REGISTRY='https://registry.npmmirror.com' (PowerShell).

Prefer nuwa-cli update (stops Gateway/tunnels, releases Windows vendor .exe locks, then runs npm). On Windows, do not run bare npm i -g @nuwax-ai/nuwa-cli@… while services are running — npm will EBUSY on locked nuwax-lanproxy.exe / nuwax-codex.exe. If you must use npm manually: nuwa-cli stop --all first, then install.

One-line uninstaller (stops services, removes the system service if installed, npm-uninstalls the global package):

# Windows (PowerShell)
irm https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.ps1 | iex

# macOS / Linux
curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.sh | bash

User data (~/.nuwa-cli: credentials / sessions / logs / workspaces) is kept by default. Purge it too:

# Windows
$env:NUWACLI_PURGE='1'; irm https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.ps1 | iex
# macOS / Linux
curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.sh | NUWACLI_PURGE=1 bash

Or via npm: npm uninstall -g @nuwax-ai/nuwa-cli (stop services first with nuwa-cli stop).

nuwa-cli doctor                          # check environment
nuwa-cli chat -p "list files"            # one-shot, claude engine
nuwa-cli chat --engine codex -p "hello"  # one-shot, codex engine
nuwa-cli console                         # web dashboard (browser)
nuwa-cli gateway --domain https://agent.nuwax.com --saved-key <key>  # cloud tunnel

nuwa-cli start                 # daemon Gateway only
nuwa-cli start --all           # Gateway + foreground Console
nuwa-cli stop                  # stop Gateway
nuwa-cli stop --all            # stop everything
nuwa-cli restart               # force-restart Gateway (kills all old processes first)
nuwa-cli restart --all         # force-restart Gateway + Console
nuwa-cli ps                    # list running processes

• Inherits your environment. No API key injection by default — engines see your existing ~/.claude / ~/.codex config, MCP servers, skills, and model preferences.
• ACP protocol. Both engines driven over Agent Client Protocol, not CLI text scraping.
• Model protocol routing. When a session supplies model_provider, nuwa-cli auto-selects the engine: api_protocol: openai → codex, api_protocol: anthropic → claude. See docs/serve-lifecycle.md.
• Cloud tunnel. --tunnel registers with Nuwax backend, starts file-server + lanproxy, and exposes the local agent to the cloud. See docs/gateway.md.
• Health checks. file-server HTTP /health polling (default 20s) + lanproxy cloud tunnel probe, with full start retry via @nuwax-ai/agent-kit withStartRetry. If file-server stays unhealthy, lanproxy is skipped. See docs/serve-health-check.md.
• Cross-platform. Windows / macOS / Linux, arm64 / x64. All spawns use windowsHide. .cmd shims auto-detected.
• S3 distribution. One-line installer from Nuwax S3 mirror; no GitHub or npm login needed. See docs/distribution-s3.md.
• Engine stderr logging. All engine stderr streamed to ~/.nuwa-cli/logs/ for diagnostics.

nuwa-cli defaults to English. Simplified Chinese (zh-CN) is shown automatically when your system locale is Simplified Chinese (LANG / LC_ALL / LC_MESSAGES / LANGUAGE containing zh, e.g. zh_CN.UTF-8, zh-Hans). Traditional Chinese locales (zh-TW / zh-HK / zh-Hant) fall back to English.

Override at any time — priority: NUWACLI_LANG env > config > auto-detect > English:

nuwa-cli lang               # show the current language and how it was resolved
nuwa-cli lang zh-CN         # persist Simplified Chinese to ~/.nuwa-cli/config.json
nuwa-cli lang en            # persist English
nuwa-cli lang auto          # follow the system locale again

NUWACLI_LANG=zh-CN nuwa-cli doctor   # one-off override (highest priority)

ACP protocol responses (HTTP / SSE / permission outcomes) are always English regardless of this setting — they are consumed by clients and engines, not humans. Only terminal output is localized. See docs/i18n.md.

nuwa-cli serve --port 60016
# POST /computer/chat            → { session_id }
# GET  /computer/progress/:id    SSE stream
# GET/POST /computer/agent/status
# POST /computer/agent/stop
# GET  /health                   (no auth)

Accepts NuwaClaw-compatible model_provider / agent_config / context_servers. Precedence: session config > Gateway flags > local environment. ACP mcpServers / context_servers are passed to the engine as raw stdio MCP servers; both TS adapters (claude-code-acp-ts / @nuwax-ai/nuwax-codex-acp-ts) handle ACP mcpServers natively at the adapter layer.

Cloud-session files are stored under:

~/.nuwa-cli/workspaces/<user_id>/<agent_work_dir>/

Use nuwa-cli status to view the registered computer name and service state.

Files generated by cloud sessions are written under the workspace directory ~/.nuwa-cli/workspaces/<user_id>/<agent_work_dir>/:

• <user_id> is your numeric Nuwax user ID;
• <agent_work_dir> is the project ID (a numeric directory) for each session.

Both IDs are visible in nuwa-cli status output or in ~/.nuwa-cli/logs/serve.*.log.

You can also list workspace directories directly from the terminal with nuwa-cli workspaces (supports --user <id>, --json, and --long to print a per-project file tree) — no need to construct the path by hand:

nuwa-cli workspaces                  # list all users / projects
nuwa-cli workspaces --user <id>      # only one user
nuwa-cli workspaces --long           # print a file tree per project

Open the workspace directory on each platform:

# macOS (Finder)
open ~/.nuwa-cli/workspaces

# Windows (PowerShell, File Explorer)
explorer "$env:USERPROFILE\.nuwa-cli\workspaces"

# Linux
xdg-open ~/.nuwa-cli/workspaces

Or list all session directories for a user from the command line:

ls -la ~/.nuwa-cli/workspaces/<user_id>/

nuwa-cli also runs a local file-server (HTTP, default port 60015, printed at serve/gateway startup) that mirrors the same workspace layout and exposes file list / preview / upload / tar endpoints — same paths the engine writes to. While serve is running it is reachable at http://127.0.0.1:60015.

See docs/serve-lifecycle.md for full lifecycle, auth, and permission details.

• Node.js >= 22
• claude and/or codex CLI installed and logged in (optional when ACP supplies model config)

• Process-tree teardown: grandchild processes (e.g. claude binary under claude-code-acp-ts) aren't signalled and may be orphaned on exit.
• No path confinement in yolo: --approve auto auto-approves all ordinary tool calls regardless of target path.
• Prompt timeout: 5 minutes per prompt; engine hangs produce an error instead of infinite wait.
• MCP startup: engines wait for MCP servers to initialize before first prompt; npm exec MCP servers may take minutes on first run. MCP servers are injected as raw stdio; both TS adapters handle ACP mcpServers natively at the adapter layer. chrome-devtools is always enabled by default as a raw stdio MCP (npx -y chrome-devtools-mcp@latest, one per session, no cross-session persistence, no --isolated). @nuwax-ai/mcp-proxy-ts remains a dependency for host adapter tool / default service merging, but is no longer used to inject a proxy entry for the engine.
• Custom ACP engines (pi-acp, hermes, kilo, etc.) not supported — only claude and codex.

English | 简体中文

无界面（headless）的多引擎 Agent 命令行工具。nuwa-cli 已内置 Codex 与 Claude 的 ACP 运行时；本机无需预装对应 CLI。若本机已有 claude / codex，会复用 ~/.claude / ~/.codex 的历史和配置；否则可完全使用 ACP 下发的模型、环境变量与 MCP 配置运行。

一键安装（S3 镜像，国内可达，自动配置 PATH）：

# Windows (PowerShell)
irm https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/install-from-s3.ps1 | iex

# macOS / Linux
curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/install-from-s3.sh | bash

或通过 npm 安装（需要 Node.js 22+）：

npm install -g @nuwax-ai/nuwa-cli@beta --progress=true
nuwa-cli doctor

npm 太慢？NUWACLI_REGISTRY=https://registry.npmmirror.com（bash）/ $env:NUWACLI_REGISTRY='https://registry.npmmirror.com'（PowerShell）。

请优先使用 nuwa-cli update（会先停 Gateway/隧道、释放 Windows 上 vendor .exe 锁，再跑 npm）。Windows 上不要在服务仍运行时裸跑 npm i -g @nuwax-ai/nuwa-cli@…——npm 会对被锁的 nuwax-lanproxy.exe / nuwax-codex.exe 报 EBUSY。若必须手动 npm：先 nuwa-cli stop --all，再安装。

一键卸载（停止服务、移除系统服务（若已安装）、npm 卸载全局包）：

# Windows (PowerShell)
irm https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.ps1 | iex

# macOS / Linux
curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.sh | bash

用户数据（~/.nuwa-cli：凭证 / 会话 / 日志 / 工作空间）默认保留。一并清除：

# Windows
$env:NUWACLI_PURGE='1'; irm https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.ps1 | iex
# macOS / Linux
curl -fsSL https://s3.nuwax.com:9443/nuwax-packages/agent-engines/nuwa-cli/uninstall-from-s3.sh | NUWACLI_PURGE=1 bash

或通过 npm：npm uninstall -g @nuwax-ai/nuwa-cli（先用 nuwa-cli stop 停服务）。

nuwa-cli doctor                          # 检查环境
nuwa-cli doctor --fix                     # 检测并自动修复可处理的问题
nuwa-cli chat -p "列出当前目录下的文件"    # 单次，claude 引擎
nuwa-cli chat --engine codex -p "hello"  # 单次，codex 引擎
nuwa-cli console                         # Web 控制台（浏览器）
nuwa-cli gateway --domain https://agent.nuwax.com --saved-key <key>  # 云端隧道

nuwa-cli start                 # 后台 Gateway
nuwa-cli start --all           # Gateway + 前台 Console
nuwa-cli stop                  # 停止 Gateway
nuwa-cli stop --all            # 停止全部
nuwa-cli restart               # 强制重启 Gateway（先杀所有旧进程）
nuwa-cli restart --all         # 强制重启 Gateway + Console
nuwa-cli ps                    # 查看运行中的进程

开机后或脚本里跑 start：若已安装登录自启，Gateway 可能已在后台拉起，start 会先等待隧道就绪再复用。做 start --force / restart 重试时请等当前命令结束，或先 nuwa-cli status 确认 Gateway 与 lanproxy 已就绪，再决定是否再次强制启动。

• 继承你的环境。 默认不注入任何凭证——引擎看到的就是你已有的 ~/.claude / ~/.codex 配置、MCP server、skills 和模型偏好。
• 走 ACP 协议。 两个引擎都通过 Agent Client Protocol 驱动，不是 CLI 文本抓取。
• 模型协议路由。 会话下发 model_provider 时，按协议自动选引擎：api_protocol: openai → codex，api_protocol: anthropic → claude。详见 docs/serve-lifecycle.md。
• 云端隧道。 --tunnel 注册到 Nuwax 后端，启动 file-server + lanproxy，把本机 Agent 暴露给云端。详见 docs/gateway.md。
• 健康检查。 启动后对 file-server HTTP /health 轮询（默认 20s）+ lanproxy 云端隧道探测，经 @nuwax-ai/agent-kit withStartRetry 完整重试；file-server 最终不健康则跳过 lanproxy。详见 docs/serve-health-check.md。
• 跨平台。 Windows / macOS / Linux，arm64 / x64。所有子进程 spawn 使用 windowsHide；.cmd 脚本自动检测。
• S3 分发。 从 Nuwax S3 镜像一键安装，无需 GitHub 或 npm 登录。详见 docs/distribution-s3.md。
• 引擎日志。 引擎 stderr 实时写入 ~/.nuwa-cli/logs/，便于诊断。

nuwa-cli 默认英文。当系统 locale 为简体中文（LANG / LC_ALL / LC_MESSAGES / LANGUAGE 含 zh，如 zh_CN.UTF-8、zh-Hans）时自动显示简体中文；繁体中文（zh-TW / zh-HK / zh-Hant）回退英文。

随时可切换——优先级：NUWACLI_LANG 环境变量 > 配置 > 自动检测 > 英文：

nuwa-cli lang               # 查看当前语言及解析来源
nuwa-cli lang zh-CN         # 持久化简体中文到 ~/.nuwa-cli/config.json
nuwa-cli lang en            # 持久化英文
nuwa-cli lang auto          # 重新跟随系统 locale

NUWACLI_LANG=zh-CN nuwa-cli doctor   # 临时覆盖（优先级最高）

ACP 协议响应（HTTP / SSE / permission 结果）始终为英文，与界面语言无关——它们是给客户端/引擎消费的协议数据，不是给人看的。只有终端输出会本地化。详见 docs/i18n.md。

nuwa-cli serve --port 60016
# POST /computer/chat            → { session_id }
# GET  /computer/progress/:id    SSE 流
# GET/POST /computer/agent/status
# POST /computer/agent/stop
# GET  /health                   （无需鉴权）

兼容 NuwaClaw 的 model_provider / agent_config / context_servers。优先级：会话配置 > Gateway 参数 > 本地环境。ACP 下发的 mcpServers / context_servers 作为原始 stdio MCP 交给引擎；claude-code-acp-ts / @nuwax-ai/nuwax-codex-acp-ts 两个 TS adapter 在 adapter 层原生处理 ACP mcpServers。

云端会话生成的本地文件位于：

~/.nuwa-cli/workspaces/<user_id>/<agent_work_dir>/

运行 nuwa-cli status 可查看“我的电脑”名称和服务状态。

云端会话生成的文件写入工作空间目录 ~/.nuwa-cli/workspaces/<user_id>/<agent_work_dir>/：

• <user_id> 是你的 Nuwax 数字用户 ID；
• <agent_work_dir> 是每次会话的项目 ID（数字目录）。

这两个 ID 可在 nuwa-cli status 输出或 ~/.nuwa-cli/logs/serve.*.log 日志里找到。

也可直接在终端用 nuwa-cli workspaces 列出工作空间目录（支持 --user <id> 过滤、--json、--long 列文件树），无需手动拼路径：

nuwa-cli workspaces                  # 列出所有用户/项目
nuwa-cli workspaces --user <id>      # 只看某个用户
nuwa-cli workspaces --long           # 列出每个项目内的文件树

各平台打开工作空间目录：

# macOS（Finder）
open ~/.nuwa-cli/workspaces

# Windows（PowerShell，资源管理器）
explorer "$env:USERPROFILE\.nuwa-cli\workspaces"

# Linux
xdg-open ~/.nuwa-cli/workspaces

或命令行浏览某个用户下的所有会话目录：

ls -la ~/.nuwa-cli/workspaces/<user_id>/

nuwa-cli 还会启动本地文件服务（HTTP，默认端口 60015，serve/gateway 启动时打印）——它镜像相同的工作空间布局，提供文件列表 / 预览 / 上传 / 打包接口，路径与引擎写入的位置一致。serve 运行时可通过 http://127.0.0.1:60015 访问。

详见 docs/serve-lifecycle.md。

• Node.js >= 22
• claude 和/或 codex CLI，已安装并登录（ACP 下发模型配置时可省略）

• 进程树清理：孙进程（如 claude-code-acp-ts 拉起的 claude 二进制）不会被信号通知，可能成为孤儿。
• yolo 无路径限制：--approve auto 对普通工具不论目标路径一律自动批准。
• Prompt 超时：每条 prompt 限时 5 分钟，引擎卡住时报错而非无限等待。
• MCP 启动：引擎等所有 MCP server 初始化后才处理首条消息；npm exec MCP server 首次可能需数分钟。MCP server 以原始 stdio 形式注入引擎，两个 TS adapter 在 adapter 层原生处理 ACP mcpServers。默认始终启用 chrome-devtools（npx -y chrome-devtools-mcp@latest，每 session 自启，无跨 session 持久化，无 --isolated）。注意：@nuwax-ai/mcp-proxy-ts 仍是依赖（host adapter 工具/默认服务合并），但不再用于给 engine 注入 proxy 入口。
• 自定义 ACP 引擎（pi-acp、hermes、kilo 等）暂不支持——仅支持 claude 和 codex。