FAQ
常见问题速查。详细机制见对应页面(链接附在各节)。
一、启动
dsh web 启动后浏览器打不开
- 监听
127.0.0.1:3080,确认进程:ps aux | grep "bin.js web" - 端口被占:
dsh web --port 8080 - 配置异常:
dsh web --dump-config看组合树
首跑 --dump-config 报错
通常是某个插件解析失败,dsh: 前缀错误会指名;删掉可疑 patch 行重试(见 启动)。
二、配置
如何换模型？
设置 → Models 加 provider(任意 OpenAI 兼容端点),会话里选;或改 settings.yaml 的 agent-default-model(见 多模型)。
默认模型怎么改？
默认模型由 agent-default-model 服务决定(要求 { provider, model }),web / headless / API 入口共用。改 settings.yaml 的 agent-default-model(或 Models 设置页)覆盖部署默认,下一次新建 Agent 生效;/plan 不切模型(见 多模型)。
cordis.patch.yml 改完不生效？
patch 在启动时组合：重启 dsh web。检查 id/name 是否匹配(见 插件)。
环境变量 / 凭据在哪设？
~/.dsh/.env(密钥)、shell 环境变量(DSH_HOME 等)、settings.yaml(结构化配置)。见 环境变量。
怎么改 DSH 主目录？
DSH_HOME 环境变量覆盖默认 ~/.dsh(装 profile、sessions、凭据、源码),改后重启生效。见 环境变量。
凭据优先级怎么排？
dsh-credentials-local 四层:进程环境(只读,恒胜)> $DSH_HOME/.credentials.yaml(托管 0600)> 工作目录 .env > $DSH_HOME/.env。见 凭据管理。
能接 Claude / GPT 的模型吗？
能。llm-pi-ai.providers 接受任意 OpenAI 兼容端点,官方 provider deepseek-official 只是默认路由;模型名、端点、key 全在本地配置,不锁厂商(见 多模型 与 选型对比)。
三、插件
卸载后启动报错？
dsh plugin remove 只删依赖、不回写手动挂载清单：检查 profile/web/cordis.patch.yml,手动删对应 insert 行。
插件面板看不到？
确认 bundle 里有 plugin-console:
dsh web --dump-config | grep plugin-console
# 没有则从 repository 源走,插件面板的 repository 机制加子路径
# (github:dsh-external/plugin-registry#main&path:/packages/plugin/console)
bundle 插件装了不生效？
重启 dsh web。bundle 需重启,repository 即改即生效。
bundle 与 repository 插件怎么选？
bundle 走 dsh plugin add(pnpm 源),重启 dsh web 生效,适合内核/需重启的包;repository 走面板 + cordis.patch.yml 行,即改即生效,适合 monorepo 子包与频繁迭代。见 插件。
session_search 为何默认不挂？
tool-session-query 是 opt-in(出厂组合默认不挂载):它把"搜历史会话"暴露给模型,跨会话访问要求 cwd 精确相等,由部署方权衡后显式挂载。底层 session-query-sqlite 默认挂载(:memory:)。见 会话检索。
e2b 如何启用？
e2b 是实验 POC、opt-in:任何出厂组合都不默认挂载。在 profile 的 cordis 配置显式声明 e2b、subprocess-e2b、fs-e2b 三行,且后两者在 e2b 之后加载;apiKey 缺省读 E2B_API_KEY。见 E2B 云沙箱。
四、数据 / 隐私
遥测怎么关？
export DSH_TELEMETRY_DISABLED=1 重启。任意非空值(含 0/false)都算关(见 隐私)。
遥测有哪几种模式？
OTel 后端(session-telemetry-otel)三模式:FULL(默认上传)/ FEEDBACK_ONLY(反馈门控)/ DISABLED;也可用 DSH_TELEMETRY_DISABLED 直接关。见 隐私。
附件存哪？
图片字节落在 <DSH_HOME>/attachments/v1/objects/<sha256-prefix>/<sha256>,owner-only;会话日志只存 sha256: 引用与校验过的元数据,不含宿主路径。见 附件。
附件支持哪些格式？
第一版只接受 PNG、JPEG、WebP、GIF;通用文件、音频、视频需要独立的生命周期(见 附件)。
spill 什么时候触发？
工具最终明文结果的 UTF-8 字节数超过 maxInlineBytes(默认 50000)时,spill-policy 把全文落盘成会话作用域文件,模型侧换有界头尾预览 + 定位符;read 结果、嵌套结果、含非文本块的结果不溢出。见 溢出存储。
spill 文件落在哪?怎么清理？
默认落在私有 0700 的临时目录(每进程);给 spill-local 配 root 可落在已知位置保留。本地溢出文件在外部清理前一直存在,无按龄保留策略(见 溢出存储)。
/feedback 与消息反馈区别？
两个契约:命令 /feedback <text> 在会话日志追加一条只读 feedback/record 事件(log-only);消息反馈(ctx.messageFeedback)是绑单条 assistant 消息的可编辑评分/备注侧车,存 storage 域。两者都不进模型上下文。见 反馈。
.anonymous-user-id 是什么？
匿名用户 ID(随机 UUID),遥测统计用;删文件重置身份。
会话记录在哪？
~/.dsh/sessions/(默认 zstd 压缩 session.jsonl.zstd,两级目录),删目录即清除(见 会话)。
五、报错排查
| 报错 / 症状 | 解法 |
|---|---|
SANDBOX_UNAVAILABLE: ... refusing to run the command unconfined | 后端不可用;装 bwrap/Landlock 或切 danger-full-access(见 沙箱) |
rewind summary (...) is not smaller than the folded region (...) | 第三方 tool-rewind 的 SHRINK;区域做大/换摘要模型/卸载 |
| 插件面板 / 设置显示不全 | 看浏览器控制台 + --dump-config 对比;缺 client 包 = bundle 未装齐 |
| 模型没反应 | 检查 .env 密钥、provider/model 是否配齐 |
六、执行与终端
terminal 与 bash 区别？
bash 是一次性命令封装(每调用一个受管子进程,无跨调用状态);PTY(ctx.terminals + terminal-bash + tool-terminal)是持久、owner 作用域的交互终端会话,状态跨工具调用保留、支持交互 stdin。PTY 不默认挂载。见 子进程与终端。
会话多久落盘一次?崩溃会丢什么？
session-checkpoint-policy 在三个边界强制落盘:模型请求前、工具外部副作用前、每个 step 边界;后台 eager write-behind + session/flush 屏障兜底。只挂持久化后端不挂该策略,崩溃可能丢 batching 窗口内的写(见 会话系统)。
七、选型对比
DSH 和 Claude Code / Codex 怎么选？
看四个变量:开源可审计性、模型绑定、成本模式、扩展机制。DSH 是三者中唯一开源 MIT、本地运行、任意 OpenAI 兼容模型端点都可接的选项,代价是 Developer Preview 期会有破坏性变更;Claude Code / Codex 开箱即用、生态稳定,但闭源且默认绑定厂商模型。能力清单三家趋同,不必逐条比。完整分析见 对比页。
DSH 是 DeepSeek 官方项目吗？
是。仓库在 deepseek-ai 官方组织下,README 标注由 DeepSeek AI 开发、MIT 许可;当前 0.1.0-rc.7 Developer Preview,官方声明会有破坏性变更。本站是社区教程站,与官方无隶属关系(见 现状页)。
DSH 适合生产环境吗？
官方状态是 Developer Preview(会有破坏性变更),但隐私基线不差:默认 loopback 监听、凭据 0600 托管、沙箱默认受限。生产使用的三条纪律:锁版本、升级看 changelog、dsh web --dump-config 验证组合树(见 现状页 与 沙箱与安全)。