设置与 doctor
This content is not available in your language yet.
命令行的行为由三处决定：配置文件（五层 settings.json）、环境变量、命令行旗标。tansr doctor 把这三处合并后的装配结果零网络地打印出来，是排障的第一步。本页按 tansr 命令行 0.10.3（2026-10-10 发布，npm @tansr/cli，内嵌 @tansr/serve 0.15.1）核对；0.10.2 / 0.10.3 没有新增命令、旗标或配置键。单文件 SEA 目前只有 Linux x64 / arm64 两档（分发点 bash.tansr.com，与 npm 同版），其它平台的安装与升级走 npm，见命令行 5 分钟跑通。
五层配置与合并规则
Section titled “五层配置与合并规则”settings.json 是 JSONC（允许注释），从五层读取，高层覆盖低层：
| 层 | 位置 | 说明 |
|---|---|---|
| managed（最高） | Windows %PROGRAMDATA%\tansr\managed-settings.json;POSIX /etc/tansr/managed-settings.json |
企业托管层 |
| projectLocal | <项目根>/.tansr/settings.local.json |
项目本地层（个人覆写，建议 gitignore） |
| projectShared | <项目根>/.tansr/settings.json |
项目共享层（随仓库分发） |
| user | ~/.tansr/settings.json（可经 TANSR_CONFIG_DIR 重定向） |
用户层 |
| builtin（最低） | 内置默认 | 兜底 |
项目根 = 从当前目录向上找最近的含 .tansr 目录的祖先。注意 ~/.tansr 本身也是一个「含 .tansr 的祖先」：当前目录落在家目录树内且沿途无项目 .tansr 时，家目录会被拾为项目根，用户配置随之兼任项目共享层。要隔离就设 TANSR_CONFIG_DIR（重定向即隔离），或在项目里放一个空 .tansr 目录显式锚定。
合并与容错：常规键深合并，高层胜；permissions / hooks / mcpServers 三段不走深合并，由内核逐层抽取并保留层归因。单键取值非法 → 剔除该键并回退更低层的值；未知键 → 告警忽略；整文件语法错误 → 该层整体跳过。一切损坏都不阻止启动，/config 可看诊断计数。$schemaVersion 当前为 1。
项目层只能收权，不能扩权：defaultMode: auto / acceptEdits / bypassPermissions 三种扩权模式在项目层声明被忽略并告警；项目层 allow 规则冻结不进引擎（经 /grants 确认后才升为仓库授权）；deny / ask 照常即时生效。克隆一个仓库不能给自己授权。自 tansr 命令行 0.7.0 起（2026-09-14 发布）：项目层 hooks 段跟随工作区信任——~/.tansr/trust.json 无记录或记为不信任时项目层 command / http hooks 零执行，无人值守入口可用 --trust-project-hooks / TANSR_TRUST_PROJECT_HOOKS=1 仅在无记录时本次放行，判据与边界见安全与隐私。自 tansr 命令行 0.6.0 起（0.5.0 候选能力并入该版发布）更严的层律：sandbox / update / http 三段只认 user 与 managed 层，managed 层是地板、环境变量对它只能收紧，组织在控制台锁定的键压过一切本地层与环境变量。
| 键 | 含义 |
|---|---|
providers / modelAliases / fallbacks |
完全本地模式的模型供给（平台模式下缺省被剪枝）；API key 只写环境变量名 auth.env |
model.selected |
/model 的持久化落点：项目内写 .tansr/settings.local.json，项目外写用户层 |
locale |
界面语言 zh-CN / en / ja / ko |
ui.theme |
dark / light / high-contrast / colorblind;/theme <name> 持久化到用户层 |
permissions.defaultMode |
六值 default / acceptEdits / plan / bypassPermissions / auto / dontAsk |
permissions.allow / ask / deny |
规则 DSL：Read、Shell(git *)、Read(./.env) 等 |
budget.maxUsd / maxTotalTokens / onExceeded |
会话预算熔断（block 缺省 / warn） |
effort / outputStyle |
思考努力档位、输出风格；优先级旗标 > 环境变量 > 本键 |
context.activeScheme |
上下文治理方案（/context scheme use 写入） |
memory.autoMemory |
自动记忆开合（`/memory on |
sandbox.mode / allowWrite / network |
Shell 沙箱（仅 user / managed 层被尊重） |
update.manifestUrl |
企业自托管更新清单地址（{channel} 占位） |
mcpServers |
MCP 服务器声明；env / headers 值支持 ${VAR} 整值引用，凭据不落文件 |
http.allowedAuthEnvVars |
Http 工具与 hooks 可引用的凭据环境变量白名单（user / managed 层） |
环境变量：用户面速查
Section titled “环境变量：用户面速查”「空串视同未设置」适用于全部路径 / 开关类变量。
| 变量 | 用途 |
|---|---|
TANSR_USER_HOME |
配置总根（虚拟用户家目录）：配置目录与存储根统一派生 <dir>/.tansr；沙箱 / CI 一键隔离 |
TANSR_CONFIG_DIR / TANSR_STORAGE_ROOT |
用户层配置根 / 会话存储根，缺省 ~/.tansr；显式设置时恒胜总根派生值 |
TANSR_PAT |
tansr init 免交互 PAT 供给（CI / 脚本） |
TANSR_ESCAPE_LOCAL |
严格 =1 进完全本地模式：平台凭据 / 远端模型 / 用量上报整体停用 |
TANSR_LANG |
界面语言（低于 --lang 与配置 locale） |
TANSR_TUI_GLYPHS / TANSR_TUI_PASTE_GUARD |
终端字形档（unicode / ascii）与多行粘贴守卫覆盖 |
TANSR_EFFORT / TANSR_OUTPUT_STYLE |
思考档位 / 输出风格 |
TANSR_SANDBOX |
=1 开沙箱、=required 硬要求 |
TANSR_ISOLATED |
=1 声明运行环境已隔离，只压制 doctor 的无人值守提示，不改运行时行为 |
TANSR_TRUST_PROJECT_HOOKS |
=1 在工作区无信任记录时本次启用项目层 hooks（等价旗标 --trust-project-hooks；不写 trust.json、压不过已记录的不信任；其余取值不生效）。命令行 0.7.0 起 |
TANSR_UPDATE_CHANNEL / TANSR_UPDATE_PINNED_VERSION / TANSR_NO_UPDATE_CHECK / TANSR_UPDATE_MANIFEST_URL |
更新通道 / 组织锁定版本 / 个人退出检查 / 自托管清单 |
TANSR_WEBSEARCH_ENDPOINT / TANSR_WEBSEARCH_API_KEY |
WebSearch 自带端点（显式设置恒压过登录态平台搜索） |
TANSR_IMAGEGEN_* / TANSR_ASR_* / TANSR_TTS_* |
媒体工具自带端点三件（_ENDPOINT / _API_KEY / _MODEL,+ TANSR_TTS_VOICE） |
TANSR_COMPILE_CACHE |
启动编译缓存目录（命令行 0.10.1 起，npm 形态）：缺省落用户缓存目录 …/tansr/compile-cache（设 TANSR_USER_HOME 时落 <TANSR_USER_HOME>/.cache/tansr/compile-cache）；=<dir> 改目录、=0 关闭。每个新安装版本首次启动多写约 2 MB、数十个文件，之后同版本启动更快；旧版本缓存不自动删，可整目录清；任何失败静默跳过 |
TANSR_SERVE_TOKEN |
tansr serve 的 Bearer（--token 缺省时回退） |
TANSR_SERVE_LOG_LEVEL |
tansr serve 日志级别，缺省 warn（命令行 0.10.0 / @tansr/serve 0.13.0 起）；此前靠 info 事件做仪表板的部署升级后要显式 =info |
TANSR_SERVE_LEGACY_V1 |
=1 在 tansr serve --v2 部署里重开 /v1 面（等价旗标 --legacy-v1）。已废弃：0.14.0 / 命令行 0.10.1 起开启即出一条 warn 事件 server.deprecated_option，1.0.0 移除；审批凭证投递改 POST /api/approvals/:id/credential 后不再需要 |
TANSR_SERVE_SSE_MAX_FRAME_BYTES / TANSR_SERVE_AUTH_MAX_PENDING / TANSR_SERVE_AUTH_TIMEOUT_MS |
SDK2 装配在场时的单帧字节硬帽（缺省 2 MiB）与基础认证源限界（缺省 128 个未结束 / 10 s）；只装 SDK1 的部署缺席零变化（命令行 0.10.0 起） |
TANSR_SERVE_LEGACY_PREFIX / TANSR_SERVE_LEGACY_SUNSET |
旧 /v2、/v3/* 前缀的退役窗口（命令行 0.10.2 起，内嵌 @tansr/serve 0.15.0）：前者取 readwrite（缺省，0.10.3 未变）/ readonly（旧前缀写操作改答 410 gone）/ off（旧前缀全部 404）；后者为 HTTP-date 或 ISO-8601，设了才在旧前缀响应附 Sunset 头。只在 --v2 部署有消费点，非 --v2 启动时按既有律出现在「legacy 组未生效」提示里；没有对应旗标 |
tansr serve 的运维旋钮（准入帽、SSE 背压、日志形态等 TANSR_SERVE_*）与 @tansr/serve 同名同义，命令行 0.10.0 起 36 键、0.10.2 起 38 键，全表见环境变量表；例如 TANSR_SERVE_LOG_FORMAT、TANSR_SERVE_MAX_ACTIVE_SESSIONS。
tansr serve 的旗标（0.10.x）
Section titled “tansr serve 的旗标（0.10.x）”| 旗标 | 含义 |
|---|---|
--token / --port / --host |
Bearer（缺省回退 TANSR_SERVE_TOKEN）、端口（缺省 7433）、监听地址（缺省回环，外部接入须显式 0.0.0.0） |
--v2 |
挂 /v2 多租户面（同一 Bearer + x-tansr-end-user 头分域，0.6.0 起）；0.10.0 起同时在链首装配统一调用面 /api，且 /v1 面缺省关闭（0.13.0 的 serve 契约变更） |
--legacy-v1 |
在 --v2 部署里重开 /v1；已废弃（0.10.1 起出 server.deprecated_option warn，1.0.0 移除），新集成改 /api |
--host-module <absolute.cjs> --host-module-sha256 <sha256> |
成对旗标（缺一即用法错误），显式装配本机绝对路径的 .cjs 受信宿主模块（≤ 16 MiB，核摘要后编译已验字节执行），@tansr/serve/extensions 的 SDK2 归档 / 缓存 / 终端服务在命令行形态只经此径可达；不传 = 0.9.0 行为（0.10.0 起） |
--trust-project-hooks |
工作区无信任记录时本次启用项目层 hooks（0.7.0 起） |
0.10.2 / 0.10.3 未新增旗标：旧前缀退役窗口只经上表的两个环境变量控制。tansr bg kill --force 在装有大量 PowerShell 模块的 Windows 机上因身份探针超时被判「不可核」而拒杀的问题已随 0.10.1 修正（wire / 旗标 / 退出码零变化）。完整命令面见命令参考，部署形态见部署与鉴权。
tansr doctor 怎么读
Section titled “tansr doctor 怎么读”tansr doctor # 人读报告;退出码 0 可用、1 有阻断问题tansr doctor --json # 机器可读它零模型调用、零网络、零子进程，全部取装配期缓存事实，适合 CI 预检。命令面参考见命令参考。TUI 内的 /doctor 是另一份页内自检：十二项 ✓ / ✗ 清单（node_version ≥ 22.19、config_sources 无 skipped 层、config_diagnostics 无 error 级、model_resolution、context_window、context_scheme 为 production 方案、custom_commands、mcp_connections、terminal 为 TTY、workspace_trust 非未信任、output_style 无坏文件、session_driver_state），只呈现、不产生退出码；两者取同一批装配期事实，但项目与结论口径不同，CI 以 tansr doctor 的退出码为准。
什么算阻断：退出码只看 --json 顶层 problems 数组（ok: true 即为空），四个问题码：
| 问题码 | 触发 |
|---|---|
no_provider |
没有可用的 provider 注册表（未登录平台，且本地 provider 未配置） |
unresolved_model |
诊断别名 main 解析失败（未知别名 / 未知 provider 等，provider.error 携结构化码） |
missing_credential |
已解析的 provider 声明了 auth.env，而该环境变量为空（本地 provider 场景；credentials.envVar 只给名、永不给值） |
session_store_unwritable |
会话存储根不可写 |
加 --connectors 时连接器自检的阻断问题并入同一数组。配置层被整体跳过、error 级配置诊断、未信任工作区、MCP 连接失败、Node 版本等都只呈现、不阻断——它们出现在报告对应段里，但不改退出码。
报告段序：版本行 → 配置五层（层 / 状态 / 路径、error 级诊断计数、被层律忽略的段、设了 TANSR_USER_HOME 时的配置总根）→ provider 解析（main → provider / 模型、来源，图片输入三态）→ 模型选择归因 → 凭据 → 剪枝 / 逃生态 → 凭据存储 → 登录档、套餐、WebSearch 来源 → 会话存储 → 更新源 → 工作区信任 → 遥测、审计、输出风格、沙箱、语义索引、媒体 → 裁决链、权限指标 → 无人值守基线 → 上下文、记忆 →（--connectors）连接器 → 结论行（问题计数）。
归因段（不计阻断，排障最常看）：
localProviders：逃生态 / 平台混用开关 / 本地 providers 剪枝来源三元组。「未配置 provider」先看这里，分清是没配还是被剪。- 凭据存储：凭据落在密钥库还是降级明文文件；派生键有效期。
- 模型选择归因：
model.selected值与提供层、项目是否钉定main、压制态是否命中。 - 套餐：登录态下一行「套餐：档名（并发上限 N）· 到期 · 状态」；个人档显「个人（仅 CLI，无套餐费）」——不是故障。
--json在顶层plan键，null= 个人档。 - 媒体工具：四面来源三态
byo/platform/none；「模型说没有图像工具」先看这行，登录了却是none通常是管理员尚未为账套开媒体池。 - 无人值守基线：
defaultMode为auto且探测不到隔离迹象时给显著提示（--json落unattended字段）；提示不阻断。 - 会话存储 / memory：会话数、总字节、工件目录数、损坏目录数；记忆索引行数与孤儿目录。只读，不代删——清理走
tansr sessions prune。 - 裁决链：启用 / 降级 / 资格档快照。
doctor 呈现的是最近一次装配拉取的事实：控制台改了套餐或能力位，跑一次 CLI 即刷新。部署连接器（OIDC / 渠道桥 / SIEM）的网络探测要显式 tansr doctor --connectors。
其他排障工具
Section titled “其他排障工具”/config：合并后配置概要与诊断计数；/status：版本 / 通道 / 语言 / 会话 / 模型。tansr -p "…" --json：完整事件流是最细的排障数据，权限判定、hook 结果、供应商切换全在流内。- Shell 工具长输出全量落盘到
<工作目录>/.tansr/shell-output/<toolCallId>.log。 tansr sessions export <id>：导出转录（密钥自动脱敏），可直接进工单。- 常见错误码与 doctor 段位的对照表见排障指南。
Was this page helpful?
Thanks for your feedback.