设置与 doctor
This content is not available in your language yet.
命令行的行为由三处决定：配置文件（五层 settings.json）、环境变量、命令行旗标。tansr doctor 把这三处合并后的装配结果零网络地打印出来，是排障的第一步。
五层配置与合并规则
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.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_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_SERVE_TOKEN |
tansr serve 的 Bearer（--token 缺省时回退） |
tansr serve 的运维旋钮（准入帽、SSE 背压、日志形态等 TANSR_SERVE_*）与 @tansr/serve 同名同义，全表见环境变量表；例如 TANSR_SERVE_LOG_FORMAT、TANSR_SERVE_MAX_ACTIVE_SESSIONS。
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 |
当前别名解析到哪个 provider / 模型 | 是（解析失败） |
context_window / context_scheme |
窗口两值（标称 / 有效）与钳位侧；活动方案 id 与阶段，非 production 方案出警示 | 否 |
custom_commands |
自定义命令源无 skipped | 否 |
mcp_connections |
懒台未连 / 已连均健康；失败台报警 | 否 |
terminal / workspace_trust / output_style |
TTY 与尺寸；未信任收紧态；当前风格 | 否 |
归因段（不计阻断，排障最常看）：
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.