跳转到内容
Qialike
首页文档

故障排除

颜色档位、同步输出、Linux 沙箱、内存与 GC、会话恢复以及工具链版本的常见问题。

排查问题前先知道两个位置：

  • 错误 / 崩溃日志：~/.dsh/qialike.log（含 [watchdog]、[row] 等诊断行；超过阈值会轮转为 .log.1）。
  • harness home：$DSH_HOME，默认 ~/.dsh（设置、凭据、会话与主题都在这里）。
Terminal window
tail -n 100 ~/.dsh/qialike.log

颜色档位不对

症状：颜色发灰、卡片与页面同色、整体看起来像 256 色而不是你终端的原生 24 位。

原因：主题色是 hex，由 Ink/chalk 输出，而 chalk 从环境变量判断色深。Ubuntu 24.04 上的 GNOME Terminal / VTE 支持 24 位却不导出 COLORTERM，于是落到 256 色档。另外，COLORTERM=24bit 不会被识别为 24 位——只认精确的 truecolor。

处理：

Terminal window
export COLORTERM=truecolor      # 标准信号
# 或只对这一次运行：
QIALIKE_COLOR=24bit qialike

可以用 QIALIKE_COLOR=256 或 QIALIKE_COLOR=16 预览低色终端下的效果。

终端不支持同步输出

症状：输入卡片的边框 / 状态行从浮层里「透出来」，或在重绘时看到半绘制的帧、画面撕裂。

原因：qialike 每一帧都用终端的同步输出模式（ESC[?2026h … ESC[?2026l）括起来。一帧是整宽重绘（120×30 下约 5.5 KB），而 pty 会把超过约 4095 字节的写入拆成多次交给终端，没有这个模式时半绘制的帧会短暂可见。

多数不认识该模式的终端会直接忽略它。若某个终端处理不当：

Terminal window
QIALIKE_NO_SYNC=1 qialike

这会改写普通帧。若画面看起来「卡死」但其实 agent 仍在工作，按任意键可立即强制重绘；内置看门狗也会自动两级强制重绘并在日志记 [watchdog] 行。

Linux 沙箱不可用（SANDBOX_UNAVAILABLE）

症状：应用启动正常、非 shell 工具可用，但每条 bash 都报 SANDBOX_UNAVAILABLE。

原因：受限 bash 优先经 bwrap（bubblewrap）运行并要求内核开启非特权 user namespace；没有 bubblewrap 时会落到 qialike 自带的 Landlock（需内核启用该 LSM，≥5.13）。两级都不可用时才会 fail-closed——这是设计，不是静默降级。

处理：

Terminal window
# 安装 bubblewrap
sudo apt install bubblewrap        # Debian / Ubuntu
sudo dnf install bubblewrap        # Fedora / RHEL
sudo pacman -S bubblewrap          # Arch


# 验证 user namespace
cat /proc/sys/kernel/unprivileged_userns_clone    # 期望 1

装好后重开 qialike。若你确认环境无法满足，临时切到 danger-full-access 可以让 bash 运行，但会放弃文件隔离。详见 沙箱与权限。

内存占用与 GC 行为

症状：RSS 随使用缓慢上升并停在一个较高的平台，看起来「越来越高」。

原因：运行时是 Bun/JSC，不会及时把已释放页面还给系统。实测同一负载下 RSS 上升后趋于平台，这是 GC 策略，不是泄漏。

处理：

Terminal window
BUN_JSC_collectContinuously=1 qialike

实测该变量让 RSS 不升反降，代价是 GC 更频繁。参考量级（整棵进程树、静置 12 秒）：

场景峰值稳态
启动 hero约 250–290 MB约 170 MB
超大会话约 330–345 MB约 225 MB

建议 ≥1 GB 内存；512 MB 可用但偏紧；低于 512 MB 不受支持。

会话恢复不符合预期

先确认三条语义：

  1. 裸执行 qialike 永远开新会话（hero 首屏），从不自动续接。
  2. qialike resume 继续当前目录下最近使用过的会话（按最后活动时间）。
  3. qialike --resume <sessionId> 恢复指定会话，优先级最高。

/sessions 与 resume 都只列当前工作目录的会话。如果你在别的目录运行，自然看不到原来的会话——用 --workspace 指回去，或先 cd 到那个目录：

Terminal window
qialike --workspace ~/proj resume

若你希望每次启动都自动续接：

{
  "resume_last": true
}

写入 ~/.dsh/qialike.json，或用 QIALIKE_RESUME_LAST=1。默认是 false。详见 快速开始。

复制与粘贴

qialike 不读终端自己的选择区：复制（拖选松开、Ctrl+Y）和粘贴（对话框里的 Shift + 右键）都走平台剪贴板工具。macOS 与 Windows 自带这些工具，Linux 不自带——所以 Linux 上「复制粘贴不生效」几乎都是没装工具，而不是 qialike 的缺陷。

Linux：先看会话类型，再装对应的工具

Terminal window
echo $XDG_SESSION_TYPE        # wayland 或 x11
Terminal window
# Wayland
sudo apt install wl-clipboard     # 提供 wl-copy / wl-paste


# X11
sudo apt install xclip             # 或 xsel

Fedora / RHEL 把 apt 换成 dnf，Arch 换成 pacman -S。

两条容易踩的坑：

  • Wayland 下只装 xclip 不够。X11 工具读的是 X 的 selection，在 Wayland 会话里通常是空的，于是能复制、粘贴却提示 clipboard is empty——必须装 wl-clipboard。
  • X11 下装了 wl-clipboard 不影响。qialike 按 wl-paste → xclip → xsel 的顺序尝试，前一个失败会自动落到下一个，两边都装也没问题。

自测时别用裸 xclip -o：它默认读 PRIMARY（鼠标中键那个选择区），不是 Ctrl+V 用的剪贴板。要加 -selection clipboard：

Terminal window
wl-paste --no-newline              # Wayland
xclip -o -selection clipboard      # X11

上面这条命令输出刚复制的内容，就说明工具这一侧是通的。

症状与处理

症状原因与处理
状态栏提示 clipboard unavailable — no clipboard tool found (install wl-clipboard, xclip or xsel)一个工具都没装。按上一节装。
状态栏提示 clipboard is empty工具装上了，但读到的选择区为空。Wayland 会话只装了 xclip 时最典型——补装 wl-clipboard。
拖选复制时状态栏有 Copied: …，粘到别的应用却没内容当时没有任何工具可用，复制走了 OSC 52 回退，而你的终端不支持或未启用它。装上 wl-clipboard / xclip 即可走原生路径。
对话框里点右键没反应这是刻意设计：普通右键太容易误触，不粘贴；用 Shift + 右键。
拖选没选中想要的文本TUI 开启了鼠标跟踪，终端不会自己处理拖选。起点落在消息列时随指针跨列继续选择；落在右侧 Steps 栏时只选该栏。

不装任何工具也能粘贴

终端自身的粘贴快捷键（macOS Cmd+V；Linux / Windows 终端通常是 Ctrl+Shift+V，个别为 Ctrl+V 或 Shift+Insert）走 bracketed paste——由终端自己读剪贴板，不经过上面这些工具。赶时间时这是最省事的路径；但它只解决「粘进来」，复制仍需工具或 OSC 52。

复制

  • 拖选后松开即复制：写入的是框架高亮的原始单元格，不受终端自身选区影响。
  • Ctrl+Y：复制当前选区的键盘等价方式（某些终端会丢失松开事件，例如 macOS Terminal.app）。
  • 成功后状态栏短暂显示 Copied: <摘要>，内容长时附带字符数。进剪贴板的是完整内容，不截断。
  • 写入顺序：macOS pbcopy；Windows clip；Linux wl-copy → xclip -selection clipboard → xsel --clipboard --input；都不可用时回退 OSC 52（iTerm2 / Kitty / Alacritty / Windows Terminal 支持；macOS Terminal.app 不支持，故那里必须靠 pbcopy）。

粘贴

  • 粘贴内容先被清洗：转义序列与控制字节被剥离（剪贴板内容可能来自任意程序），单行输入框里的换行会折成空格，单次插入上限 4096 字符。成功后状态栏显示 pasted N chars。
  • 读取剪贴板需要平台工具（仅 Shift + 右键 这条路径）：macOS 用系统自带的 pbpaste，Windows 用 powershell.exe，Linux 见上。
  • 粘贴图片：把图片文件拖进输入框（终端会把其路径作为文本粘贴），或直接粘贴一个本地图片路径——qialike 会识别并读取该文件，以 [Image: 文件名] 附件挂在输入框上，随消息作为图片内容块发出。

其他症状

症状可能原因与处理
模型显示 not set没有激活的供应商（key 被删或供应商被隐藏）。用 /models 配置一个 key。
模型输出到长度上限且没有正文发送任意消息继续，或用 Ctrl+T 调低推理档减少额度消耗。
审批对话框从不出现沙箱能正常强制时，通常没有工具会请求审批。但执行器不提供内核隔离时，逐次 shell 审批会接管——此时对话框会出现，并在提示里说明该命令拥有你的完整用户权限。
仓库 overlay 导致启动被拒绝仓库级 overlay 里可能含会 spawn 进程的行。运行 qialike plugin list 查看状态，或 qialike plugin trust-overlay 审阅后信任。
qialike web 拒绝启动未安装 dsh CLI，或版本与本 qialike 内嵌的 harness 不一致；按提示安装匹配版本。
qialike: command not found（刚装完）PATH 写进了 profile，但当前 shell 还没读到——source ~/.bashrc（zsh 用 ~/.zshrc）或重开终端。
Terminal too small — keys paused终端高度不足：此界面最小需要 14 行（宽 ≥110 列才显示右侧栏）。把窗口调高即可，按键会自动恢复。
EADDRINUSE端口被占。服务端冲突用 qialike web --port <n> 换端口；只在本机冲突则只改 SSH 映射即可（-L 8080:localhost:3080），服务端不必重启、token URL 也不变。
401 dsh web authentication required用了不带 token 的地址——用服务启动时打印的那条 URL，且别在 127.0.0.1 与 localhost 之间切换。
自动更新一直没来要么这份二进制没人管（源码构建、手动解压的 zip 永远不会被替换；curl 安装器那份也只在 Linux / macOS 自动更新），要么 qialike-update.auto 是 false 或 "notify"，要么设了 QIALIKE_DISABLE_AUTOUPDATE=1。Windows 上只有 npm 装的副本会自动更新。见 更新。
想知道有哪些请求离开本机、以及怎么关掉qialike 自身没有分析或遥测；harness 的遥测是反馈门控（FEEDBACK_ONLY），只有新的显式反馈才会释放一段有界会话前缀。用 DSH_TELEMETRY_MODE=DISABLED 关闭。见 配置 → 数据与责任。

下一步