openclaw completion¶

生成 shell 补全脚本，将其缓存在 OpenClaw 状态目录下，并可选择安装到你的 shell 配置文件中。

用法¶

openclaw completion                          # print the detected shell's script
openclaw completion --shell fish             # print fish script
openclaw completion --write-state            # cache scripts for all shells
openclaw completion --write-state --install  # cache, then install in one step
openclaw completion --shell bash --write-state

选项¶

• -s, --shell <shell>: shell 目标，取值为 zsh、bash、powershell 或 fish 之一。从 $SHELL 检测；否则在 Windows 上为 PowerShell，在其他系统上为 zsh。
• -i, --install: 通过向 shell 配置文件添加缓存脚本的 source 行来安装补全
• --write-state: 将补全脚本写入 $OPENCLAW_STATE_DIR/completions（默认 ~/.openclaw/completions），不输出到标准输出。使用 --shell 时只写入该 shell，否则写入全部四种。
• -y, --yes: 跳过安装确认提示（非交互式）

安装流程¶

--install 会将你的配置文件指向缓存脚本，因此缓存必须已存在。如果缓存缺失，命令会失败并提示你运行 openclaw completion --write-state。组合使用 --write-state --install 可以在一步中完成两者。未指定 --shell 时，命令会保留已识别的 $SHELL。当 $SHELL 缺失或无法识别时，默认在 Windows 上使用 PowerShell，在其他系统上使用 zsh。

安装会向你的 shell 配置文件写入一个小型 # OpenClaw Completion 块，并用缓存的 source 行替换任何旧的、较慢的 source <(openclaw completion ...) 行：

配置文件更改会先在目标文件旁边暂存，并只有在完整持久化写入完成后才原子性地替换目标文件。安装失败时，现有配置文件保持不变。

已安装的 source 行会保留字面缓存路径，包括空格、引号、美元符号和反斜杠。在状态目录更改后重新安装，会替换 OpenClaw 之前的 source 行。

用户自行管理的、针对同一缓存脚本的可移植钩子（例如 [[ -f "${HOME}/.openclaw/completions/openclaw.bash" ]] && source "${HOME}/.openclaw/completions/openclaw.bash"，就像 dotfile 管理器会写入的那样）会被识别为已配置补全。Doctor 和 completion --install 会逐字节保留此类受管理的行，而不是追加重复的字面路径块。

权限失败¶

如果 Doctor 或引导流程无法更新你的 shell 配置文件，补全仍保持可选，设置会继续进行。当缓存可用时，警告会包含一条命令，用于在当前匹配的 shell 会话中加载该缓存。请完整运行打印出的命令。这不会为未来的 shell 会话安装补全。

为了持久安装，请在重试 openclaw completion --install 之前解决报告的权限或只读错误。失败位置可能是暂存目录或符号链接目标，而不是配置文件本身。原子替换还需要对目标目录具有写入权限。安装程序使用上表中选择的配置文件。它没有配置文件目标选项。

备注¶

• 未使用 --install 或 --write-state 时，命令会将脚本打印到标准输出。
• 补全生成会立即加载完整命令树，包括插件 CLI 命令，因此嵌套子命令也会被包含。
• 如果无效配置阻止插件发现，生成过程会发出警告，但仍会包含核心命令。修复配置并重新生成，以包含插件命令。
• Bash 补全同时支持 --flag value 和 --flag=value，包括嵌套命令之前的命名配置文件，以及单引号、双引号或反斜杠转义的值前缀。
• 在选项终止符（--）之后，Bash 会补全命令名称，但不会建议选项或选项值。
• PowerShell 会在光标处补全命令和选项值，即使后续参数已经存在也是如此。
• openclaw update 会自动刷新核心补全缓存，而不会加载插件 CLI 命令。运行 openclaw completion --write-state 以包含插件命令。openclaw doctor 可以修复缺失或过期的补全设置。

相关¶

• CLI 参考