范围与规则

更新于 2026年11月10日

CLI 机器只能访问您授予它的内容。范围在批准时选择,之后可在设置 › CLI 机器中修改(或在 app.konsolity.com/cli-machines 上修改,需打开保险库)。范围会被双重执行:一是服务器,它会拒绝范围之外的任何调用;二是机器本身,它会执行服务器既无法读取也无法修改的加密规则。两者都会拒绝未被允许的操作。

域

域 允许的操作
hosts 列出所选主机;在完全访问下,可在这些主机上运行命令(konsolity run)。
snippets 列出所选代码片段;在完全访问且具有 hosts 时,可运行它们(konsolity snippet run)。
sessions 查看账户中正在运行的 CLI 会话并结束它们(konsolity sessions)。
mcp 作为 Claude 代理的工具(konsolity mcp、konsolity serve)。

默认:hosts 和 snippets。

只读或完全访问

  • 只读:仅限列表和状态。不能运行任何命令,通过代码片段也不行。这是默认的访问方式,适合仪表板或监控。
  • 完全访问:允许在所选主机上运行命令,但须符合下文的命令规则。

机器保险库

机器永远不会收到您保险库的密钥。批准时,您的设备会随机生成一把该机器专用的机器密钥,将其加密封装后交给机器,然后用这把密钥加密,仅复制范围所允许的条目:

  • 所选主机,及其身份、SSH 密钥和已固定的主机密钥;
  • 所选代码片段;
  • 机器的规则。

服务器将这些副本作为不透明数据块存储。范围之外的主机没有副本:其 SSH 密钥永远不会离开您的保险库。机器无法访问账户的保险库。

  • 将主机添加到范围:由一台保险库已打开的设备写入其副本。
  • 移除主机:服务器会立即删除其副本。
  • 在保险库中编辑主机(地址、密钥):您的设备会在下次同步时更新各台机器的副本。删除主机也会删除其副本。

只有主机密钥已在保险库中固定的主机才能使用:CLI 从不接受未知的主机密钥(host_key_unknown)。请先从应用连接一次该主机以固定其密钥。

命令规则

在完全访问下,只有当主机在范围内,并且命令(去掉首尾空格后)与某条规则匹配时,才允许运行 konsolity run(以及 Claude 的 run_command 工具)。共有三种比较方式:

类型 规则 示例模式 接受 拒绝
exact 整条命令完全相同 df -h df -h df -h /
prefix 命令以该模式开头 uptime uptime -p w
glob * 代表一串字符 systemctl status * systemctl status nginx systemctl restart nginx

* 永远不允许的内容

在 glob 模式中,* 不能包含:

  • ; & |(命令串联和管道);
  • ` 和 $((命令替换);
  • > 和 <(重定向);
  • 换行符。

因此,systemctl status * 既不接受 systemctl status nginx; rm -rf /,也不接受 systemctl status x | sh。prefix 模式会原样接受前缀之后的任何内容:请仅将其用于无害的命令。

任意命令

任意命令选项允许在所选主机上运行任何文本。它要求在屏幕上明确确认,并且不建议使用:机器将等同于拥有完整的 shell 访问权限。破坏性命令仍然需要确认(见下文)。

以完全访问激活时,默认不勾选任何规则,“任意命令”也处于关闭状态:您必须编写规则或明确勾选“任意命令”,否则所有自由命令都会被拒绝。允许的代码片段按其保存时的内容运行。

最大超时时间

任何命令超过最大超时时间都会被停止:默认 60 秒,最长 1 小时。通过 --timeout 或由 Claude 请求的值始终以此超时时间为上限。

破坏性命令:始终需要确认

无论范围如何,即使启用了“任意命令”,某些命令在未经您在应用或控制台中明确确认之前也绝不会运行。如果命令(或代码片段的内容)以独立单词的形式包含以下内容,即被视为破坏性命令,例如:

  • 删除和擦除:rm -r、rm -f、rmdir、shred、truncate、dd、mkfs、fdisk、parted、wipefs;
  • 停机:shutdown、reboot、poweroff、halt、init 0、init 6、systemctl stop、disable、mask、kill、service ... stop、kill -9、killall、pkill;
  • 账户和权限:userdel、deluser、passwd、chmod -R、chown -R、crontab -r;
  • 防火墙:iptables -F、ufw disable、ufw reset;
  • 数据库:DROP、TRUNCATE、DELETE FROM、ALTER TABLE ... DROP、migrate:fresh、migrate:reset、migrate:rollback;
  • 代码仓库和基础设施:git push --force、git reset --hard、git clean -f、docker rm、docker rmi、docker system prune、docker volume rm、docker compose down -v、kubectl delete、terraform destroy;
  • 指向磁盘(/dev/sd*、/dev/nvme*)或 /etc/ 的 > 重定向。

CLI 和服务器使用同一份列表:未经批准确认就启动的破坏性命令会在两端都被拒绝。具体流程请参阅确认。

修改范围

  • 扩大范围(添加域,从只读改为完全访问)需要再次进行第二重验证(TOTP 或通行密钥)。
  • 缩小范围(移除域,改回只读,移除主机)立即生效,无需任何验证:范围之外的副本会被立即删除。

命令规则和超时时间可随时修改,需打开保险库。如需查看机器实际执行的内容:

konsolity policy

示例

监控(只读,hosts + sessions):列表和状态,不运行命令。

日常运维(完全访问,少量主机):

glob     systemctl status *
exact    df -h
exact    free -m
prefix   uptime
glob     journalctl -u * --since *
glob     tail -n * /var/log/nginx/error.log
exact    docker ps

再加上代码片段“重启 nginx”和“清除应用缓存”。

从 CI 部署(长期令牌,完全访问,hosts + snippets):在生产主机上只有一个“部署”代码片段,没有自由命令规则。