DeepSeek-Reasonix 配置路径完全指南Reasonix Home、全局 config.toml 与 .env 凭据体系【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix自Reasonix v1.8.1起Reasonix 统一使用一个面向用户的主目录Reasonix Home承载全局配置与用户自有状态CLI 与桌面端共享同一套路径约定。本文基于仓库文档 docs/CONFIG_PATHS.md结合 internal/config/paths.go、internal/config/migrate.go、internal/config/dotenv.go 等源码系统讲解 Reasonix Home 的目录布局、全局config.toml与.env的编写规则、配置优先级以及从旧版本含 v0.x TypeScript 版本自动迁移与手动救援的完整流程。读完本文你将能准确回答Reasonix 的配置到底放在哪、谁优先、密钥存在哪、旧数据怎么搬这四个核心问题。Reasonix Home唯一面向用户的全局目录各平台的默认位置Reasonix Home 是全局配置与用户状态的主目录CLI 与桌面应用共用。默认位置按平台区分平台Reasonix homemacOS~/.reasonixLinux~/.reasonixWindows%APPDATA%\reasonix从源码看Windows 上优先使用os.UserConfigDir()即%APPDATA%当%APPDATA%不可用时回退到%USERPROFILE%\AppData\Roaming\reasonixmacOS/Linux 则优先取用户主目录下的.reasonix其次才回退到系统配置目录见 internal/config/paths.go#L47-L67。用REASONIX_HOME覆盖主目录普通用户通常无需关心环境变量但以下三类场景需要显式覆盖测试与 CI隔离运行环境避免污染真实配置便携式安装把整套 Reasonix 随目录携带数据隔离与系统级生产安装完全分离。设置REASONIX_HOME后运行时完全自包含所有配置、状态、缓存、数据都落在该目录树之下。此时旧版迁移、OS 主目录约定目录扫描如~/.config/reasonix、~/.claude等以及其他所有回退路径全部被跳过确保不会从系统级生产安装泄漏任何数据。这一点在源码中有明确佐证IsolatedHomeDir()返回非空即代表自包含运行时而 internal/config/paths.go#L224-L226 的注释直接声明此时不得回退到旧版 OS 默认数据路径或从系统级安装导入数据internal/config/migrate.go#L97-L100 中MigrateLegacyIfNeededForRoot也首先检查IsolatedHomeDir()命中即跳过全部迁移。注意REASONIX_HOME的值会经过~展开与相对路径绝对化处理见cleanEnvDirinternal/config/paths.go#L182-L203。REASONIX_STATE_HOME仅移动运行时状态进阶的测试与便携场景还可设置REASONIX_STATE_HOME用于把运行时状态会话、归档、记忆等挪到别处。两条关键规则它不会移动全局配置与 provider 凭据——这两者始终留在REASONIX_HOME下如果旧版本构建曾把 provider 密钥写到REASONIX_STATE_HOME/.env当Reasonix home/.env缺少这些键时Reasonix 会非破坏性地导入它们。源码中userSupportDir()即state root解析器优先返回REASONIX_STATE_HOME否则回退到reasonixHomeDir()internal/config/paths.go#L146-L151。缓存目录的独立控制缓存默认留在操作系统缓存目录macOS~/Library/Caches/reasonixLinux$XDG_CACHE_HOME/reasonix或~/.cache/reasonixWindows%LOCALAPPDATA%\reasonix\cache可用REASONIX_CACHE_HOME覆盖缓存根。特别地当设置了REASONIX_HOME时缓存默认落到$REASONIX_HOME/cache除非同时设置了REASONIX_CACHE_HOME后者优先。该优先级逻辑见 internal/config/paths.go#L168-L180。缓存目录存放的是可再生的派生产物如 MCP 握手快照、插件启动延迟遥测internal/config/paths.go#L530-L539 的注释明确说明缓存best-effort、可容忍缺失。目录里到底放了什么以下表格是 Reasonix HomeReasonix home、state rootstate root与 cache rootcache root下的数据布局state root默认等于Reasonix home仅在设置REASONIX_STATE_HOME时不同数据路径全局配置Reasonix home/config.toml全局 provider 凭据Reasonix home/.env旧凭据导入源Reasonix home/credentials全局斜杠命令Reasonix home/commands/全局技能Reasonix home/skills/全局钩子Reasonix home/settings.jsonRemote-SSH 托管的 known_hostsReasonix home/remote/known_hosts会话state root/sessions/归档state root/archive/记忆state root/memory/与state root/projects/全局桌面主题元数据state root/desktop/topic-state-v1.sqlite项目桌面主题元数据state root/projects/workspace slug/desktop/topic-state-v1.sqlite一次性会话目录cache root/session-catalog/v6.sqlite一次性历史搜索目录cache root/history-search/v1.sqlite一次性用量目录cache root/usage-catalog/v1.sqlite一次性任务目录cache root/task-catalog/v1.sqlite几个值得展开的要点会话按项目归档项目级会话存放在state root/projects/workspace slug/sessions。workspace slug 由绝对工作区路径扁平化而来——Windows 上先折叠大小写避免同一目录因盘符大小写或 Explorer 改名产生多个 slug再把路径分隔符与冒号替换为-并截断到 255 字节的文件名上限超出部分追加 FNV-1a 哈希见 internal/config/paths.go#L490-L520。桌面主题元数据权威在 SQLite主题标题、标题来源、创建时间与自动标题状态都以这些 SQLite 文件为准。首次访问时桌面端会把项目.reasonix/目录或全局 Reasonix 目录下的旧版desktop-topic-*.json文件导入进来。带旧文件的作用域会继续镜像它们以兼容降级全新作用域则不会创建旧文件。旧文件被保留且项目本地的设置、技能、命令、附件和reasonix.toml完全不受影响。对应路径实现见 internal/config/paths.go#L468-L481。四个 SQLite 目录都是可重建的查询投影会话 JSONL、事件日志、元数据 sidecar 与desktop-projects.json才是权威数据源。会话目录详见 Session Catalog 与桌面启动历史投影见 History Search Catalog用量汇总投影见 Usage Catalog跨项目任务快照投影见 Task Catalog。配置文件的命名约定全局用户配置固定命名为config.toml即Reasonix home/config.toml项目本地配置保持reasonix.toml的名称。如果有人说全局 reasonix.toml通常指的就是Reasonix home/config.toml。全局config.tomlCLI 与桌面共享的非敏感配置Reasonix home/config.toml存储 CLI 与桌面应用共享的非敏感配置可包含 Reasonix 渲染进用户配置的 provider、插件、UI、桌面、工具、技能、沙箱、bot 与 agent 设置。provider 条目只存凭据变量的名字api_key_env绝不存密钥值本身。已保存的 provider 与 bot 凭据变量会被从每个由模型控制的子进程环境中移除全局凭据.env也对其文件读取器、沙箱化 shell 命令和 MCP 服务器隐藏——但这不改变项目普通.env的可见性。Windows 上 shell 命令仍在操作系统沙箱之外运行详见 GUIDE.md因此只应对可信任务批准 shell 访问。完整配置示例config_version 1 default_model deepseek/deepseek-v4-flash language zh credentials_store auto # legacy compatibility; provider keys are in .env [ui] theme auto cursor_shape bar # CLI/TUI text cursor: underline|block|bar show_turn_usage false # hide per-request token/cost receipts in the TUI; default true [desktop] provider_access [deepseek] [[providers]] name deepseek kind anthropic base_url https://api.deepseek.com/anthropic models [deepseek-flash, deepseek-v4-flash, deepseek-v4-pro, deepseek-v4-flash-vision-exp] default deepseek-v4-flash api_key_env DEEPSEEK_API_KEY web_search true [[plugins]] name example command example-mcp-server要点说明credentials_store auto仅用于旧版兼容——provider 密钥实际都放在.env不要把 API 密钥写进config.toml。该文件是普通配置在标准脱敏后可以安全地检查、编辑、迁移、纳入诊断。密钥属于下面的全局.env[ui].cursor_shape只影响 CLI/TUI 输入框光标。默认bar在覆盖双宽 CJK 字符时仍然可见如偏好其他形状可用block或underline[ui].show_turn_usage false隐藏每轮模型请求后追加在 TUI 转录末尾的 token 与费用回执但计费统计与实时状态更新仍然生效该字段默认值为true。自定义 provider 的api_key_env命名规则通过桌面设置或reasonix setup添加自定义 provider 时Reasonix 会把一个生成的api_key_env存入config.toml同时把密钥值写入全局.env的对应键。生成的名字是稳定的因此同一 provider 重启后仍使用同一个凭据槽位。命名规则如下纯 ASCII 名称规范化后得到可读的环境变量名例如LOCAL_GATEWAY_API_KEY全非 ASCII 名称追加稳定哈希后缀例如CUSTOM_d39b9067_API_KEY——避免两个中文 provider 名字撞车到同一个CUSTOM_API_KEY以数字开头加上CUSTOM_前缀使生成的环境变量名合法例如9router→CUSTOM_9ROUTER_API_KEY。CLI 自定义 provider 向导会先用 base URL 生成 provider 名再套用同一命名规则。例如https://token.sensenova.cn/v1会生成 provider 名custom-token-sensenova-cn其默认 key env 为CUSTOM_TOKEN_SENSENOVA_CN_API_KEY。按回车接受默认名或显式输入CUSTOM_API_KEY以便在多个 provider 间共享同一个凭据。升级时不会重写既有配置旧的自定义 provider 若已使用CUSTOM_API_KEY会继续用该键工作。若多个旧 provider 意外共享了CUSTOM_API_KEY请逐个修改每个 provider 的api_key_env为不同名称并重新保存对应的 API 密钥。自定义 provider 的端点 URL 语义桌面自定义 provider 表单把API 地址当作精确请求 URL存入request_urlReasonix不会对其路径做追加或改写。这是当前桌面 UI 的语义request_url、models_url、extra_body字段的 TOML 定义见 internal/config/config.go#L1339-L1348。相关兼容规则既有 TOML 条目不会被重新解释旧版chat_url保持其仅限 OpenAI 的行为Anthropic 与 Responses 协议继续从base_url推导路径直到该 provider 在当前桌面 UI 中显式保存过保存一个 OpenAI 兼容 provider 时会把精确地址镜像进旧版chat_url使先前版本继续使用同一目标但先前版本无法处理任意的 Anthropic 或 Responses 请求路径若模型发现需要独立地址设置models_url否则 Reasonix 会探测从base_url派生的候选若网关需要厂商专属的顶层请求体字段用extra_body例如extra_body { enable_thinking true }。这些值会被合并进 OpenAI 兼容的 chat JSON 请求体但不允许覆盖model、messages、tools、stream等核心字段。全局.envprovider 凭据的唯一运行时来源Reasonix home/.env是 Reasonix 保存的 provider API 密钥的单一运行时来源。设置向导、桌面设置、CLI 缺钥提示、provider 密钥删除操作全部通过同一套凭据辅助函数读写该文件。结构示例DEEPSEEK_API_KEYsk-... GEMINI_API_KEY... ANTHROPIC_API_KEY... # reasonix-cleared OLD_API_KEY读写规则每行一个KEYvalue赋值忽略空行与#注释读取时接受export KEYvalue形式与带引号的值写入时拒绝多行值键名必须使用 shell 风格名称如DEEPSEEK_API_KEY# reasonix-cleared KEY注释是非敏感的墓碑标记某键被删除后写入防止旧存储静默地把它重新导入在操作系统支持受限权限的情况下Reasonix 会以受限权限写该文件。解析边界哪些不是 provider 凭据回退源发起 provider 请求时Reasonix只解析这个全局.env。以下内容都不会作为运行时 provider 密钥回退项目.env文件主目录.env文件继承的 shell 环境变量旧版credentials文件操作系统 keyring。项目.env、主目录.env与继承的 shell 环境值也不会被导入全局凭据文件。旧版credentials文件与旧 keyring 条目只作为非破坏性迁移源被读取——仅当新全局.env缺少某个键时才读取相关实现见 internal/config/dotenv.go#L373-L435 的migrateLegacyCredentialsIfNeededForRoot它优先读旧凭据文件、再探测 keyring且用 marker 文件避免反复探测。不过项目.env仍有它的用途它作为工作区作用域、非 provider 的展开来源为 MCP/插件 env、headers、URL、命令与参数中的${VAR}引用提供值。这些值不会被写进进程环境且其中的REASONIX_HOME、REASONIX_STATE_HOME、XDG_CONFIG_HOME等 Reasonix 控制变量会被忽略源码中isProjectDotEnvControlKey明确过滤REASONIX_前缀及 HOME 类变量见 internal/config/dotenv.go#L57-L72。配置优先级运行时配置按以下顺序解析先出现的胜出command-line flags project ./reasonix.toml global Reasonix home/config.toml compatible legacy global config built-in defaults写操作始终落到新的全局路径macOS/Linux: ~/.reasonix/config.toml Windows: %APPDATA%\reasonix\config.toml从源码看配置加载时会先查项目reasonix.toml再查全局配置加载路径含旧版回退路径见 internal/config/paths.go#L69-L91 的userConfigLoadPath与 internal/config/paths.go#L637-L659 的SourcePathForRoot。命令行为什么必须最高因为--continue/--resume、临时模型覆盖等一次性操作不该污染持久配置。Legacy Migration从 v1.8.1 起的自动迁移自v1.8.1起Reasonix 在首次加载配置前的启动阶段自动检查旧版位置。迁移是同步、一次性、非破坏性的旧文件被复制或转换到 Reasonix Home且保持原样不动源码中MigrateLegacyIfNeeded的注释明确never modifies or deletes the legacy files见 internal/config/migrate.go#L88-L92。会被检查的旧版配置源~/Library/Application Support/reasonix/config.toml ~/.config/reasonix/config.toml ~/.reasonix/reasonix.toml ~/.reasonix/config.json注意最后一个是v0.x 的~/.reasonix/config.jsonTypeScript 时代的配置迁移代码为它定义了专门的兼容结构承载apiKey、baseUrl、model、lang、MCP 服务器mcp/mcpServers/mcpEnv/mcpDisabled与 QQ 机器人配置等字段见 internal/config/migrate.go#L19-L53。迁移覆盖的数据与规则凭据、记忆文件、会话在新目标不存在时导入进 Reasonix Home旧 provider 密钥仅当Reasonix home/.env尚不含相同键时才复制过去缺失的键才补已有键绝不覆盖旧 TOML 与 JSON转换后写入新config.tomlapiKey转为DEEPSEEK_API_KEY写入.envQQ Bot AppSecret 转为QQ_BOT_APP_SECRET旧版 base URL 语义官方 DeepSeek 端点转换为 Anthropic 协议与/anthropic前缀非官方 base URL 保持 OpenAI 兼容协议不强行套用新 Anthropic 默认值见 internal/config/migrate.go#L582-L612会话格式转换v0.x 的事件日志name.events.jsonl被重建为 v1 消息格式name.jsonl按 sidecar.meta.json中的工作区路由到项目目录已经处于 v1 消息格式的.jsonl直接复制.jsonl.bak在正本丢失时兜底恢复工具调用从旧版嵌套function结构扁平化为新格式完整实现见 internal/agent/migrate.go 的migrateLegacySessionsWithMarkers含多轮 pass 与rehomeStrandedSessions降级兜底支持数据目录sessions、projects、skills、archive、hooks.json、settings.json等会随 TOML 迁移一并复制见 internal/config/migrate.go#L714-L751新配置已存在时新配置胜出旧版配置文件仅作为兼容回退保留。v1.9.1 的 MCP 全局回填自v1.9.1起Reasonix 还会把来自已知旧路径、旧版config.json、桌面注册项目与恢复的标签页项目中的 MCP 服务器回填到全局Reasonix home/config.toml。关键规则已存在的全局[[plugins]]条目按名称胜出——项目或旧版条目永远不会覆盖用户已在全局配置好的服务器源文件保持不动回填会写入一次性 marker位于 state root 下的mcp-global-migration-v1防止用户删除某个全局 MCP 服务器后它又被旧项目配置反复重建见 internal/config/migrate.go#L188-L303。Manual Migration Rescue/migrate手动救援如果 Reasonix 已经创建了新主目录、但某些旧数据当时尚未就位或桌面应用在旧路径可用之前就被打开过可以在两个前端里运行迁移救援命令/migrateCLI TUI在聊天输入框输入/migrate桌面应用在 composer 里输入同样的命令。该命令会边执行边打印进度通知依次检查旧版配置与凭据扫描已知的旧版记忆位置扫描已知的旧版会话目录导入之前未导入的记忆文件与会话打印最终汇总。命令在斜杠命令注册表中以/migrate别名/migration注册见 internal/cli/slash_registry.go#L64。指定自定义旧目录/migrate --from如果旧 v0.x 会话位于已知旧位置之外——例如 Windows v0.52 安装时选择的安装/数据目录——需要显式传入目录/migrate --from D:\OldReasonix显式形式只导入会话。路径可以是旧安装目录、.reasonix/data 目录或sessions目录本身Reasonix 会检查该根目录下的常见布局并使用来源特定 marker对传入路径做 SHA-256 摘要生成的.legacy-imported.explicit.hash见 internal/agent/migrate.go#L95-L102因此先前跑过的普通/migrate不会遮蔽这次导入。救援命令的非破坏性保证不会覆盖已存在的Reasonix home/config.toml——若新配置已存在请手工把缺失的旧设置复制过去旧记忆文件仅在目标文件缺失时复制尊重会话导入 marker——已导入后被用户删除的会话不会在后续/migrate中复活。版本边界自动迁移从v1.8.1开始/migrate仅在包含该命令的 Go 版 Reasonix 构建中可用若提示unknown command请先升级再重试旧版0.xTypeScript 产品线中没有该命令普通/migrate只重扫上文列出的旧位置/migrate --from path仅用于已知的 v0.x 会话来源——它不是备份恢复工具也不是降级导入器。实践清单排查配置问题的正确姿势最后整理一份可操作的排查清单覆盖最常见的配置场景找不到全局配置确认平台对应的 Reasonix HomemacOS/Linux~/.reasonixWindows%APPDATA%\reasonix配置文件是config.toml不是reasonix.toml密钥没生效确认密钥在Reasonix home/.env而非config.tomlconfig.toml中 provider 的api_key_env必须与.env中的键名一致项目.env不会作为 provider 凭据回退测试/CI 想完全隔离设置REASONIX_HOME指向临时目录此时所有旧路径扫描与迁移都会被跳过只想搬状态设置REASONIX_STATE_HOME配置与凭据仍留在REASONIX_HOME升级后旧数据消失先确认新主目录是否已存在若存在但缺数据在两个前端的输入框运行/migratev0.x 会话在已知位置之外时用/migrate --from 目录自定义网关不通核对request_url/base_url/chat_url语义差异当前桌面 UI 保存后按request_url精确请求必要时设置models_url并用extra_body传厂商专属字段MCP 服务器被反复重建v1.9.1 的全局回填带一次性 marker若你删除了全局 MCP 服务器却被旧项目配置复活请检查是否有旧reasonix.toml仍在被扫描并直接编辑Reasonix home/config.toml的[[plugins]]列表。这套路径体系的设计核心是一个主目录、两类文件config.toml.env、三级覆盖flags 项目 全局配合非破坏性迁移机制让长期运行的 CLI 与桌面端在升级、便携部署与多环境切换时都保持可预期、可回退、可诊断。【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepSeek-Reasonix 配置路径完全指南：Reasonix Home、全局 config.toml 与 .env 凭据体系
DeepSeek-Reasonix 配置路径完全指南Reasonix Home、全局 config.toml 与 .env 凭据体系【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix自Reasonix v1.8.1起Reasonix 统一使用一个面向用户的主目录Reasonix Home承载全局配置与用户自有状态CLI 与桌面端共享同一套路径约定。本文基于仓库文档 docs/CONFIG_PATHS.md结合 internal/config/paths.go、internal/config/migrate.go、internal/config/dotenv.go 等源码系统讲解 Reasonix Home 的目录布局、全局config.toml与.env的编写规则、配置优先级以及从旧版本含 v0.x TypeScript 版本自动迁移与手动救援的完整流程。读完本文你将能准确回答Reasonix 的配置到底放在哪、谁优先、密钥存在哪、旧数据怎么搬这四个核心问题。Reasonix Home唯一面向用户的全局目录各平台的默认位置Reasonix Home 是全局配置与用户状态的主目录CLI 与桌面应用共用。默认位置按平台区分平台Reasonix homemacOS~/.reasonixLinux~/.reasonixWindows%APPDATA%\reasonix从源码看Windows 上优先使用os.UserConfigDir()即%APPDATA%当%APPDATA%不可用时回退到%USERPROFILE%\AppData\Roaming\reasonixmacOS/Linux 则优先取用户主目录下的.reasonix其次才回退到系统配置目录见 internal/config/paths.go#L47-L67。用REASONIX_HOME覆盖主目录普通用户通常无需关心环境变量但以下三类场景需要显式覆盖测试与 CI隔离运行环境避免污染真实配置便携式安装把整套 Reasonix 随目录携带数据隔离与系统级生产安装完全分离。设置REASONIX_HOME后运行时完全自包含所有配置、状态、缓存、数据都落在该目录树之下。此时旧版迁移、OS 主目录约定目录扫描如~/.config/reasonix、~/.claude等以及其他所有回退路径全部被跳过确保不会从系统级生产安装泄漏任何数据。这一点在源码中有明确佐证IsolatedHomeDir()返回非空即代表自包含运行时而 internal/config/paths.go#L224-L226 的注释直接声明此时不得回退到旧版 OS 默认数据路径或从系统级安装导入数据internal/config/migrate.go#L97-L100 中MigrateLegacyIfNeededForRoot也首先检查IsolatedHomeDir()命中即跳过全部迁移。注意REASONIX_HOME的值会经过~展开与相对路径绝对化处理见cleanEnvDirinternal/config/paths.go#L182-L203。REASONIX_STATE_HOME仅移动运行时状态进阶的测试与便携场景还可设置REASONIX_STATE_HOME用于把运行时状态会话、归档、记忆等挪到别处。两条关键规则它不会移动全局配置与 provider 凭据——这两者始终留在REASONIX_HOME下如果旧版本构建曾把 provider 密钥写到REASONIX_STATE_HOME/.env当Reasonix home/.env缺少这些键时Reasonix 会非破坏性地导入它们。源码中userSupportDir()即state root解析器优先返回REASONIX_STATE_HOME否则回退到reasonixHomeDir()internal/config/paths.go#L146-L151。缓存目录的独立控制缓存默认留在操作系统缓存目录macOS~/Library/Caches/reasonixLinux$XDG_CACHE_HOME/reasonix或~/.cache/reasonixWindows%LOCALAPPDATA%\reasonix\cache可用REASONIX_CACHE_HOME覆盖缓存根。特别地当设置了REASONIX_HOME时缓存默认落到$REASONIX_HOME/cache除非同时设置了REASONIX_CACHE_HOME后者优先。该优先级逻辑见 internal/config/paths.go#L168-L180。缓存目录存放的是可再生的派生产物如 MCP 握手快照、插件启动延迟遥测internal/config/paths.go#L530-L539 的注释明确说明缓存best-effort、可容忍缺失。目录里到底放了什么以下表格是 Reasonix HomeReasonix home、state rootstate root与 cache rootcache root下的数据布局state root默认等于Reasonix home仅在设置REASONIX_STATE_HOME时不同数据路径全局配置Reasonix home/config.toml全局 provider 凭据Reasonix home/.env旧凭据导入源Reasonix home/credentials全局斜杠命令Reasonix home/commands/全局技能Reasonix home/skills/全局钩子Reasonix home/settings.jsonRemote-SSH 托管的 known_hostsReasonix home/remote/known_hosts会话state root/sessions/归档state root/archive/记忆state root/memory/与state root/projects/全局桌面主题元数据state root/desktop/topic-state-v1.sqlite项目桌面主题元数据state root/projects/workspace slug/desktop/topic-state-v1.sqlite一次性会话目录cache root/session-catalog/v6.sqlite一次性历史搜索目录cache root/history-search/v1.sqlite一次性用量目录cache root/usage-catalog/v1.sqlite一次性任务目录cache root/task-catalog/v1.sqlite几个值得展开的要点会话按项目归档项目级会话存放在state root/projects/workspace slug/sessions。workspace slug 由绝对工作区路径扁平化而来——Windows 上先折叠大小写避免同一目录因盘符大小写或 Explorer 改名产生多个 slug再把路径分隔符与冒号替换为-并截断到 255 字节的文件名上限超出部分追加 FNV-1a 哈希见 internal/config/paths.go#L490-L520。桌面主题元数据权威在 SQLite主题标题、标题来源、创建时间与自动标题状态都以这些 SQLite 文件为准。首次访问时桌面端会把项目.reasonix/目录或全局 Reasonix 目录下的旧版desktop-topic-*.json文件导入进来。带旧文件的作用域会继续镜像它们以兼容降级全新作用域则不会创建旧文件。旧文件被保留且项目本地的设置、技能、命令、附件和reasonix.toml完全不受影响。对应路径实现见 internal/config/paths.go#L468-L481。四个 SQLite 目录都是可重建的查询投影会话 JSONL、事件日志、元数据 sidecar 与desktop-projects.json才是权威数据源。会话目录详见 Session Catalog 与桌面启动历史投影见 History Search Catalog用量汇总投影见 Usage Catalog跨项目任务快照投影见 Task Catalog。配置文件的命名约定全局用户配置固定命名为config.toml即Reasonix home/config.toml项目本地配置保持reasonix.toml的名称。如果有人说全局 reasonix.toml通常指的就是Reasonix home/config.toml。全局config.tomlCLI 与桌面共享的非敏感配置Reasonix home/config.toml存储 CLI 与桌面应用共享的非敏感配置可包含 Reasonix 渲染进用户配置的 provider、插件、UI、桌面、工具、技能、沙箱、bot 与 agent 设置。provider 条目只存凭据变量的名字api_key_env绝不存密钥值本身。已保存的 provider 与 bot 凭据变量会被从每个由模型控制的子进程环境中移除全局凭据.env也对其文件读取器、沙箱化 shell 命令和 MCP 服务器隐藏——但这不改变项目普通.env的可见性。Windows 上 shell 命令仍在操作系统沙箱之外运行详见 GUIDE.md因此只应对可信任务批准 shell 访问。完整配置示例config_version 1 default_model deepseek/deepseek-v4-flash language zh credentials_store auto # legacy compatibility; provider keys are in .env [ui] theme auto cursor_shape bar # CLI/TUI text cursor: underline|block|bar show_turn_usage false # hide per-request token/cost receipts in the TUI; default true [desktop] provider_access [deepseek] [[providers]] name deepseek kind anthropic base_url https://api.deepseek.com/anthropic models [deepseek-flash, deepseek-v4-flash, deepseek-v4-pro, deepseek-v4-flash-vision-exp] default deepseek-v4-flash api_key_env DEEPSEEK_API_KEY web_search true [[plugins]] name example command example-mcp-server要点说明credentials_store auto仅用于旧版兼容——provider 密钥实际都放在.env不要把 API 密钥写进config.toml。该文件是普通配置在标准脱敏后可以安全地检查、编辑、迁移、纳入诊断。密钥属于下面的全局.env[ui].cursor_shape只影响 CLI/TUI 输入框光标。默认bar在覆盖双宽 CJK 字符时仍然可见如偏好其他形状可用block或underline[ui].show_turn_usage false隐藏每轮模型请求后追加在 TUI 转录末尾的 token 与费用回执但计费统计与实时状态更新仍然生效该字段默认值为true。自定义 provider 的api_key_env命名规则通过桌面设置或reasonix setup添加自定义 provider 时Reasonix 会把一个生成的api_key_env存入config.toml同时把密钥值写入全局.env的对应键。生成的名字是稳定的因此同一 provider 重启后仍使用同一个凭据槽位。命名规则如下纯 ASCII 名称规范化后得到可读的环境变量名例如LOCAL_GATEWAY_API_KEY全非 ASCII 名称追加稳定哈希后缀例如CUSTOM_d39b9067_API_KEY——避免两个中文 provider 名字撞车到同一个CUSTOM_API_KEY以数字开头加上CUSTOM_前缀使生成的环境变量名合法例如9router→CUSTOM_9ROUTER_API_KEY。CLI 自定义 provider 向导会先用 base URL 生成 provider 名再套用同一命名规则。例如https://token.sensenova.cn/v1会生成 provider 名custom-token-sensenova-cn其默认 key env 为CUSTOM_TOKEN_SENSENOVA_CN_API_KEY。按回车接受默认名或显式输入CUSTOM_API_KEY以便在多个 provider 间共享同一个凭据。升级时不会重写既有配置旧的自定义 provider 若已使用CUSTOM_API_KEY会继续用该键工作。若多个旧 provider 意外共享了CUSTOM_API_KEY请逐个修改每个 provider 的api_key_env为不同名称并重新保存对应的 API 密钥。自定义 provider 的端点 URL 语义桌面自定义 provider 表单把API 地址当作精确请求 URL存入request_urlReasonix不会对其路径做追加或改写。这是当前桌面 UI 的语义request_url、models_url、extra_body字段的 TOML 定义见 internal/config/config.go#L1339-L1348。相关兼容规则既有 TOML 条目不会被重新解释旧版chat_url保持其仅限 OpenAI 的行为Anthropic 与 Responses 协议继续从base_url推导路径直到该 provider 在当前桌面 UI 中显式保存过保存一个 OpenAI 兼容 provider 时会把精确地址镜像进旧版chat_url使先前版本继续使用同一目标但先前版本无法处理任意的 Anthropic 或 Responses 请求路径若模型发现需要独立地址设置models_url否则 Reasonix 会探测从base_url派生的候选若网关需要厂商专属的顶层请求体字段用extra_body例如extra_body { enable_thinking true }。这些值会被合并进 OpenAI 兼容的 chat JSON 请求体但不允许覆盖model、messages、tools、stream等核心字段。全局.envprovider 凭据的唯一运行时来源Reasonix home/.env是 Reasonix 保存的 provider API 密钥的单一运行时来源。设置向导、桌面设置、CLI 缺钥提示、provider 密钥删除操作全部通过同一套凭据辅助函数读写该文件。结构示例DEEPSEEK_API_KEYsk-... GEMINI_API_KEY... ANTHROPIC_API_KEY... # reasonix-cleared OLD_API_KEY读写规则每行一个KEYvalue赋值忽略空行与#注释读取时接受export KEYvalue形式与带引号的值写入时拒绝多行值键名必须使用 shell 风格名称如DEEPSEEK_API_KEY# reasonix-cleared KEY注释是非敏感的墓碑标记某键被删除后写入防止旧存储静默地把它重新导入在操作系统支持受限权限的情况下Reasonix 会以受限权限写该文件。解析边界哪些不是 provider 凭据回退源发起 provider 请求时Reasonix只解析这个全局.env。以下内容都不会作为运行时 provider 密钥回退项目.env文件主目录.env文件继承的 shell 环境变量旧版credentials文件操作系统 keyring。项目.env、主目录.env与继承的 shell 环境值也不会被导入全局凭据文件。旧版credentials文件与旧 keyring 条目只作为非破坏性迁移源被读取——仅当新全局.env缺少某个键时才读取相关实现见 internal/config/dotenv.go#L373-L435 的migrateLegacyCredentialsIfNeededForRoot它优先读旧凭据文件、再探测 keyring且用 marker 文件避免反复探测。不过项目.env仍有它的用途它作为工作区作用域、非 provider 的展开来源为 MCP/插件 env、headers、URL、命令与参数中的${VAR}引用提供值。这些值不会被写进进程环境且其中的REASONIX_HOME、REASONIX_STATE_HOME、XDG_CONFIG_HOME等 Reasonix 控制变量会被忽略源码中isProjectDotEnvControlKey明确过滤REASONIX_前缀及 HOME 类变量见 internal/config/dotenv.go#L57-L72。配置优先级运行时配置按以下顺序解析先出现的胜出command-line flags project ./reasonix.toml global Reasonix home/config.toml compatible legacy global config built-in defaults写操作始终落到新的全局路径macOS/Linux: ~/.reasonix/config.toml Windows: %APPDATA%\reasonix\config.toml从源码看配置加载时会先查项目reasonix.toml再查全局配置加载路径含旧版回退路径见 internal/config/paths.go#L69-L91 的userConfigLoadPath与 internal/config/paths.go#L637-L659 的SourcePathForRoot。命令行为什么必须最高因为--continue/--resume、临时模型覆盖等一次性操作不该污染持久配置。Legacy Migration从 v1.8.1 起的自动迁移自v1.8.1起Reasonix 在首次加载配置前的启动阶段自动检查旧版位置。迁移是同步、一次性、非破坏性的旧文件被复制或转换到 Reasonix Home且保持原样不动源码中MigrateLegacyIfNeeded的注释明确never modifies or deletes the legacy files见 internal/config/migrate.go#L88-L92。会被检查的旧版配置源~/Library/Application Support/reasonix/config.toml ~/.config/reasonix/config.toml ~/.reasonix/reasonix.toml ~/.reasonix/config.json注意最后一个是v0.x 的~/.reasonix/config.jsonTypeScript 时代的配置迁移代码为它定义了专门的兼容结构承载apiKey、baseUrl、model、lang、MCP 服务器mcp/mcpServers/mcpEnv/mcpDisabled与 QQ 机器人配置等字段见 internal/config/migrate.go#L19-L53。迁移覆盖的数据与规则凭据、记忆文件、会话在新目标不存在时导入进 Reasonix Home旧 provider 密钥仅当Reasonix home/.env尚不含相同键时才复制过去缺失的键才补已有键绝不覆盖旧 TOML 与 JSON转换后写入新config.tomlapiKey转为DEEPSEEK_API_KEY写入.envQQ Bot AppSecret 转为QQ_BOT_APP_SECRET旧版 base URL 语义官方 DeepSeek 端点转换为 Anthropic 协议与/anthropic前缀非官方 base URL 保持 OpenAI 兼容协议不强行套用新 Anthropic 默认值见 internal/config/migrate.go#L582-L612会话格式转换v0.x 的事件日志name.events.jsonl被重建为 v1 消息格式name.jsonl按 sidecar.meta.json中的工作区路由到项目目录已经处于 v1 消息格式的.jsonl直接复制.jsonl.bak在正本丢失时兜底恢复工具调用从旧版嵌套function结构扁平化为新格式完整实现见 internal/agent/migrate.go 的migrateLegacySessionsWithMarkers含多轮 pass 与rehomeStrandedSessions降级兜底支持数据目录sessions、projects、skills、archive、hooks.json、settings.json等会随 TOML 迁移一并复制见 internal/config/migrate.go#L714-L751新配置已存在时新配置胜出旧版配置文件仅作为兼容回退保留。v1.9.1 的 MCP 全局回填自v1.9.1起Reasonix 还会把来自已知旧路径、旧版config.json、桌面注册项目与恢复的标签页项目中的 MCP 服务器回填到全局Reasonix home/config.toml。关键规则已存在的全局[[plugins]]条目按名称胜出——项目或旧版条目永远不会覆盖用户已在全局配置好的服务器源文件保持不动回填会写入一次性 marker位于 state root 下的mcp-global-migration-v1防止用户删除某个全局 MCP 服务器后它又被旧项目配置反复重建见 internal/config/migrate.go#L188-L303。Manual Migration Rescue/migrate手动救援如果 Reasonix 已经创建了新主目录、但某些旧数据当时尚未就位或桌面应用在旧路径可用之前就被打开过可以在两个前端里运行迁移救援命令/migrateCLI TUI在聊天输入框输入/migrate桌面应用在 composer 里输入同样的命令。该命令会边执行边打印进度通知依次检查旧版配置与凭据扫描已知的旧版记忆位置扫描已知的旧版会话目录导入之前未导入的记忆文件与会话打印最终汇总。命令在斜杠命令注册表中以/migrate别名/migration注册见 internal/cli/slash_registry.go#L64。指定自定义旧目录/migrate --from如果旧 v0.x 会话位于已知旧位置之外——例如 Windows v0.52 安装时选择的安装/数据目录——需要显式传入目录/migrate --from D:\OldReasonix显式形式只导入会话。路径可以是旧安装目录、.reasonix/data 目录或sessions目录本身Reasonix 会检查该根目录下的常见布局并使用来源特定 marker对传入路径做 SHA-256 摘要生成的.legacy-imported.explicit.hash见 internal/agent/migrate.go#L95-L102因此先前跑过的普通/migrate不会遮蔽这次导入。救援命令的非破坏性保证不会覆盖已存在的Reasonix home/config.toml——若新配置已存在请手工把缺失的旧设置复制过去旧记忆文件仅在目标文件缺失时复制尊重会话导入 marker——已导入后被用户删除的会话不会在后续/migrate中复活。版本边界自动迁移从v1.8.1开始/migrate仅在包含该命令的 Go 版 Reasonix 构建中可用若提示unknown command请先升级再重试旧版0.xTypeScript 产品线中没有该命令普通/migrate只重扫上文列出的旧位置/migrate --from path仅用于已知的 v0.x 会话来源——它不是备份恢复工具也不是降级导入器。实践清单排查配置问题的正确姿势最后整理一份可操作的排查清单覆盖最常见的配置场景找不到全局配置确认平台对应的 Reasonix HomemacOS/Linux~/.reasonixWindows%APPDATA%\reasonix配置文件是config.toml不是reasonix.toml密钥没生效确认密钥在Reasonix home/.env而非config.tomlconfig.toml中 provider 的api_key_env必须与.env中的键名一致项目.env不会作为 provider 凭据回退测试/CI 想完全隔离设置REASONIX_HOME指向临时目录此时所有旧路径扫描与迁移都会被跳过只想搬状态设置REASONIX_STATE_HOME配置与凭据仍留在REASONIX_HOME升级后旧数据消失先确认新主目录是否已存在若存在但缺数据在两个前端的输入框运行/migratev0.x 会话在已知位置之外时用/migrate --from 目录自定义网关不通核对request_url/base_url/chat_url语义差异当前桌面 UI 保存后按request_url精确请求必要时设置models_url并用extra_body传厂商专属字段MCP 服务器被反复重建v1.9.1 的全局回填带一次性 marker若你删除了全局 MCP 服务器却被旧项目配置复活请检查是否有旧reasonix.toml仍在被扫描并直接编辑Reasonix home/config.toml的[[plugins]]列表。这套路径体系的设计核心是一个主目录、两类文件config.toml.env、三级覆盖flags 项目 全局配合非破坏性迁移机制让长期运行的 CLI 与桌面端在升级、便携部署与多环境切换时都保持可预期、可回退、可诊断。【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
