CLI

Kaiwu CLI 是面向高级用户的客户端，可用于：

安装与更新 Kaiwu
针对单台或多台服务器进行身份认证
选择默认服务器配置，或单次指定目标服务器执行命令
创建、查看、恢复、附加和管理会话
运行外部 Kaiwu MCP 服务器
检查 Kaiwu 工具以及动作驱动的工作流

安装

curl -fsSL https://kaiwu.wujilabs.cn/install | bash

公共安装通道：

stable: curl -fsSL https://kaiwu.wujilabs.cn/install | bash -> kaiwu
preview: curl -fsSL https://kaiwu.wujilabs.cn/install-preview | bash -> hprev
dev: curl -fsSL https://kaiwu.wujilabs.cn/install-dev | bash -> hdev

Windows（PowerShell）：

irm https://kaiwu.wujilabs.cn/install.ps1 | iex

npm 备用方案（面向高级用户 / Node 工作流）：

npm install -g @Kaiwu-dev/cli

重要提示：

通过 npm 安装会直接使用 npm dist-tag（@latest 和 @next）。
滚动更新通道 dev 由安装程序统一管理（install-dev / hdev），并非独立的 npm dist-tag。

引导式首次运行

kaiwu setup

在全新交互式安装中，安装程序会直接进入 kaiwu setup。如果安装过程采用无人值守模式、你跳过了引导步骤，或者登录未能完成，可以手动运行该命令。设置向导会询问你的中继位置，将当前电脑指向该中继，并执行登录。只有当满足以下全部条件时，向导才会跳过这台电脑并不作变动：已选定中继、该中继依然认可保存的登录凭据，且当前设备已在该中继上完成注册。若凭据已被中继拒绝，或凭据未关联已注册设备，这正是设置向导要修复的情况，因此不会视为配置完成。若所选中继没有响应，则无法进行任何验证：向导会原样保留所选中继与已保存的登录凭据，提示无法校验，并允许重试或明确选择其他中继——中继不可达绝不会被视为凭据被拒，也不是改用其他中继登录的理由。

安装程序自动交接给设置向导遵循尽力而为原则：拒绝交接或未完成设置，并不会导致原本成功的二进制安装被判定为失败。但明确指定的安装程序操作（例如 --run setup）则不同：该操作属于你主动执行的命令的一部分，因此会传递其退出状态码。非零结果表示 CLI 已安装完毕，但请求的设置操作未能完成。

参数标志	效果
`--cloud`	直接使用 Kaiwu Cloud，无需确认
`--relay ⟦K36⟧`	使用已在运行的中继
`--this-computer`	在当前电脑上安装并使用中继
`--yes`	不做任何询问，执行所有无需交互的操作，停在登录环节
`--non-interactive`	不做任何更改，仅列出需要执行的操作

--yes 与 --non-interactive 的行为互斥，无法组合使用。--yes 会执行已有预设答案的步骤：将本机指向你指定的中继；若指定了 --this-computer，还会将中继安装在本地。随后流程会暂停，因为登录必须在手机端或浏览器中确认，命令行无法代你完成授权。安装向导会提示 kaiwu auth login 并以非零状态退出——这意味着二进制文件已安装，但引导配置尚未完成。它需要 --cloud、--relay ⟦K37⟧ 或 --this-computer 之一：由于你的账户存储在所选的中继上，安装向导不会擅自代你做出选择。

--non-interactive 不会写入任何内容。在检测到 KAIWU_NONINTERACTIVE=1（或旧版 Kaiwu_NONINTERACTIVE=1）以及无终端运行环境时，安装向导的处理方式也是如此，而这正是安装程序和 CI 在整个运行期间所采用的设置——对于仅用于中转的设备，系统不会在上面创建账户。如需执行实际操作，请通过 --yes 显式声明。

选择在本机托管中继会在安装前后各增加一个连通性检查步骤：安装向导会说明本机上的 Tailscale 是正在运行、已安装但已停止，还是根本未安装，以及这对你的手机意味着什么。否则，中继无法被手机访问的问题往往要到之后在其他地方才会发现。若未安装 Tailscale，安装向当中继最终只能从这台电脑访问时（例如未配置 Tailscale，或是使用了回环地址），登录步骤会提示该状态，并通过当前电脑的浏览器完成登录，而不再提供 App 选项。终端链接会刻意过滤掉其他设备无法访问的地址，因此手机仍会保持指向原有的中继。只有真正发起新请求的登录才会触发这一逻辑：无论如何，设置流程都会运行 kaiwu auth login；若之前保存的登录状态依然有效，它只会在不打开浏览器的情况下修复设备注册。一旦中继拥有了手机可访问的地址，kaiwu auth login 便会重新同时提供这两种途径。

设置的最后一步是检查是否已安装编程智能体。未检测到仅作为警告处理，不算失败——你可以先完成设置，稍后再行安装。

检查与修复本设备

kaiwu status 会读取你与可用会话之间的整条链路——涵盖账号、中继注册、开机自启及 CLI 通道，且不做任何更改。kaiwu doctor repair 则会尽力修复其中的问题。两者的用法均在检查配置中有详细介绍，该章节还一并介绍了用于管理开机自启的 kaiwu service 命令。

通过脚本发送通知

在任何能运行 Shell 的地方向自己的设备发送通知——例如漫长的构建结束时、定时任务执行时，或是部署流程中：

kaiwu notify -p "Deployment complete!"
kaiwu notify -p "Database connection restored" -t "Alert"

-p 为消息内容，-t 为可选标题。

自动化

无需打开 App 即可触发已保存的自动化：

kaiwu automation run <automation-id> [--idempotency-key <key>] [--json]

若调用方可能会重试，请传入 --idempotency-key——重复的 key 不会重复运行该自动化。

插件

kaiwu plugins list [--json]

当前版本的 Kaiwu 不支持安装插件。提供此命令是为了让查询插件的工具收到正常的空响应，而不是报错提示命令无法识别。该命令列出的内容始终为空。

服务器配置

保存并切换服务器

kaiwu server list
kaiwu server current
kaiwu server add --name company --server-url https://api.company.example --webapp-url https://app.company.example --use
kaiwu server use company

--use（以及 kaiwu server use ...）会为后续命令设置默认服务器，选定后通常可以省略 --server ...。

针对单条命令指定服务器

如果不想切换默认服务器，可以在单次执行命令时单独指定：

kaiwu --server company auth login
kaiwu --server personal daemon status

也可以使用 URL 参数：

kaiwu --server-url https://api.company.example --webapp-url https://app.company.example auth login
kaiwu --server-url https://api.company.example --webapp-url https://app.company.example auth pair-remote --ssh user@host --json

kaiwu logout 已弃用并会输出提示信息。请改用 kaiwu auth logout。

守护进程（后台模式）

如需使用常驻后台会话、远程控制和无头服务器，请参阅守护进程。

接入现有会话

如果支持的会话已在运行，你可以从终端重新接入该实时会话：

kaiwu attach
kaiwu attach <session-id>

这是“App 内发起，终端中继续”的核心工作流。在受支持的 TTY 环境中，kaiwu attach 会打开活动会话的交互式选择器：

本地可接入会话可直接选择
处于活动状态但不可接入的会话保持可见，但会被禁用并显示原因
支持远程的提供商会话会标记为远程；在选择器中按 P 可在接入前运行连通性检查

若会话已停止，请改用 kaiwu resume。

注意事项：

tmux 及其他终端宿主接入流程，仅适用于仍归当前设备所有的会话。
你必须指向拥有该会话的同一 Kaiwu 账号/服务器配置文件。

接入策略取决于具体的提供商：

部分提供商使用基于 Kaiwu tmux 的接入流程。
对于基于服务器的会话，OpenCode 使用提供商原生接入流程。

对于 OpenCode，受支持的重新接入命令仍为 kaiwu attach ⟦K40⟧。在 Kaiwu 的常规工作流中，请勿直接依赖厂商底层的 opencode attach ... 命令。

受支持的接入方式包括：

在已启用 tmux 的设备上基于 tmux 的会话
Windows 上由 Windows Terminal 或 控制台 托管的会话
针对 OpenCode 等受支持提供商会话的提供商原生接入

完整工作流请参见功能 → 接入正在运行的会话。

恢复非活跃会话

若 Kaiwu 会话处于非活跃状态，但提供商仍支持恢复，你可以直接通过 CLI 将其恢复。

交互式选择器

kaiwu resume

在受支持的 TTY 环境中，Kaiwu 会显示一个交互式选择器，列出可恢复的非活跃会话。

通过 ID 恢复

kaiwu resume <session-id>

你可以使用完整的会话 ID，也可以使用无歧义的前缀。

重要行为：

严格恢复机制：若提供商恢复失败，Kaiwu 会直接报错，而不会启动全新的会话
已归档或已处于活跃状态的会话无法恢复
该命令会在重新启动提供商之前，先恢复会话的工作目录

如需查看完整的用户指南以及“可恢复”的具体含义，请参阅功能 → 恢复非活动会话。

列出会话

运行以下命令：

kaiwu session list

默认输出为一个表格，包含会话 ID、智能体、最近活动、活跃状态、恢复状态、标题及路径。

常用变体：

kaiwu session list --resumable
kaiwu session list --plain
kaiwu session list --json

--resumable 仅筛选当前可恢复的会话
--plain 恢复旧版单行输出格式
--json 适用于脚本调用

会话控制（非交互式）

kaiwu session ... 命令组是非交互式创建与控制会话的接口。

详细参考：CLI 会话。

创建会话（可脚本化）

kaiwu session create --title "My session" --message "Hello"

指定目标（可选）：

kaiwu session create --path /path/to/repo --backend <backend-target-key> --tag <tag>

--backend 需要传入后端目标键（而非简写名称）。常见形式如下：

# Built-in catalog agent
kaiwu session create --backend "agent:<agent-id>"

# ACP backend target (e.g. opencode, gemini, etc)
kaiwu session create --backend "acpBackend:<backend-id>"

发送消息

kaiwu session send <session-id> "ping"

等待 Agent 响应（适用于脚本；若 Agent 处于繁忙或离线状态可能会超时）：

kaiwu session send <session-id> "ping" --wait --timeout 60

状态、停止与归档

kaiwu session status <session-id>
kaiwu session history <session-id>
kaiwu session wait <session-id> --timeout 60
kaiwu session stop <session-id>
kaiwu session archive <session-id>
kaiwu session unarchive <session-id>

设置标题 / 模型 / 权限模式

kaiwu session set-title <session-id> "New title"
kaiwu session set-model <session-id> <model-id>
kaiwu session set-permission-mode <session-id> <mode>

⟦K41⟧ 支持常用别名（例如 ask、default、yolo）。可以通过 --json 编写脚本并查看规范化后的 permissionMode 值。

会话 ID 前缀

接受 ⟦K42⟧ 的命令支持使用完整会话 ID 的无歧义前缀。

若前缀匹配到多个会话，命令将执行失败并列出候选会话。

来自 CLI 命令的审批

部分动作可在 CLI 操作端配置为需审批门禁。

此时，CLI 命令不会立即执行，而是会创建一条审批请求。你可以使用 App 的收件箱来审核、批准或拒绝，并查看最终的执行结果：

对于高级自动化场景，审批也可以通过通用动作执行器进行判定：

kaiwu session actions execute <session-id> approval.request.decide --input-json '{"artifactId":"<id>","decision":"approve"}' --json

通过 CLI 查看动作目录

你可以直接查看并执行 Kaiwu 动作：

kaiwu session actions list
kaiwu session actions describe <action-id>
kaiwu session actions execute <session-id> <action-id> --input-json '<json>'

执行运行（review / plan / delegate / voice agent）

执行运行是会话中多步骤流程的结构化“运行”层（例如：先启动一次 review 运行，再发送跟进消息，最后停止）。

kaiwu session run list <session-id>
kaiwu session run start <session-id> --intent <intent> --backend <backend-target-key>
kaiwu session run send <session-id> <run-id> "message"
kaiwu session run stop <session-id> <run-id>

外部 MCP 控制面

若要通过 MCP 宿主（编辑器/智能体）控制 Kaiwu 会话和操作，请运行外部 MCP 服务器：

kaiwu mcp serve

kaiwu mcp start 可作为兼容别名使用，但文档和 CLI 帮助中的规范命令名称为 serve。

指南：Kaiwu MCP（外部）

后端配置

CLI 支持后端配置，可用于启动会话及配置发现：

kaiwu profiles list
kaiwu claude --profile deepseek
kaiwu codex --profile openai

完整指南请参阅功能 → 配置。

Kaiwu 工具

CLI 还直接提供了统一的 Kaiwu 工具接口。

适用于以下场景：

查看当前有哪些内置 Kaiwu 工具可用
查看在当前设备/工作区上下文中解析出了哪些自定义 MCP 工具
直接在终端中调用其中某个工具

列出工具

kaiwu tools list

可选参数：

kaiwu tools list --directory /path/to/project

此操作会列出：

Kaiwu 内置工具
针对所选目录和设备解析出的自定义 MCP 工具

list 不需要会话 ID。

调用工具

kaiwu tools call --session-id <session-id> --source Kaiwu --tool action_spec_search --args-json '{"query":"plan mode","limit":5}'

示例：

--source Kaiwu --tool review_start
--source Kaiwu --tool subagents_plan_start
--source Kaiwu --tool action_spec_get
--source Kaiwu --tool action_options_resolve
--source playwright --tool browser_navigate

若尚不确定确切的 action id 或合法的选项值，可以使用 Kaiwu 内置的发现工具。

若要了解更全面的产品模型，请参阅 Kaiwu 工具与操作。

多服务器参考

有关多服务器与多守护进程的完整指南，请参见功能 → 多服务器。

安装

更新

身份认证

远程设备配对（SSH，自动化）

配对（JSON，手动 / 脚本）