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 homeCLI 与桌面端共用这一套路径解析、凭据存储与迁移机制。本文基于官方文档 docs/CONFIG_PATHS.zh-CN.md并结合仓库源码internal/config/paths.go、internal/config/credentials.go、internal/migration/migration.go 等展开讲解。读完本文你将掌握Reasonix home 在 macOS/Linux/Windows 上的精确位置、REASONIX_HOME/REASONIX_STATE_HOME/REASONIX_CACHE_HOME三个覆盖变量的语义、全局config.toml与全局.env的职责边界与完整配置写法、自定义 provider 的api_key_env命名规则以及从 v1.8.1 之前旧路径自动迁移和/migrate手动补救的完整操作流程。一、Reasonix Home全局配置与状态的唯一入口1.1 各平台的默认位置CLI 与桌面端共享同一个全局目录默认位置随平台不同平台Reasonix homemacOS~/.reasonixLinux~/.reasonixWindows%APPDATA%\reasonix从源码 internal/config/paths.go 可以确认这一解析顺序非 Windows 平台优先取~/.reasonixWindows 优先取%APPDATA%\reasonix即os.UserConfigDir()/reasonix当%APPDATA%不可用时回退到%USERPROFILE%\AppData\Roaming\reasonix。1.2 REASONIX_HOME完整自包含模式可以通过设置环境变量REASONIX_HOME覆盖 Reasonix home官方定位是测试、CI 或便携安装场景普通用户通常不需要设置。设置REASONIX_HOME后运行时进入完整自包含模式配置、状态、缓存和数据全部位于该目录树下互不干扰Legacy 迁移、OS home 约定目录扫描以及其他 fallback 路径全部跳过避免从系统级正式安装带入或写回数据。源码中的IsolatedHomeDir()internal/config/paths.go就是这一隔离机制的实现只要REASONIX_HOME被显式设置迁移逻辑internal/config/migrate.go与/migrate补救命令internal/migration/migration.go都会直接短路跳过。另外注意 internal/config/paths.go 中cleanEnvDir的实现细节REASONIX_HOME支持~与~/xxx写法会被展开为 home 目录、支持${VAR}展开且相对路径会被转为绝对路径路径末尾会被清理。1.3 REASONIX_STATE_HOME仅移动运行状态高级测试或便携安装还可以设置REASONIX_STATE_HOME用于移动sessions、archive、memory等运行状态。需要注意的边界它不会移动全局配置或 provider 凭据这些仍然位于REASONIX_HOME或默认 home下如果旧版本曾把 provider key 写到REASONIX_STATE_HOME/.envReasonix 会在Reasonix home/.env缺少对应 key 时非破坏性导入。源码中userSupportDir()internal/config/paths.go即 state root 的实现设置REASONIX_STATE_HOME时直接返回该目录否则回落到 Reasonix home。SessionDir、ArchiveDir、StatsDir、MemoryUserDirinternal/config/paths.go 与 L544-L546都基于这个 state root 展开。1.4 REASONIX_CACHE_HOME缓存根目录缓存是可丢弃数据默认放在系统缓存目录macOS~/Library/Caches/reasonixLinux$XDG_CACHE_HOME/reasonix或~/.cache/reasonixWindows%LOCALAPPDATA%\reasonix\cache可通过REASONIX_CACHE_HOME覆盖缓存根目录。优先级规则见 internal/config/paths.goREASONIX_CACHE_HOME优先级最高设置REASONIX_HOME且未设置REASONIX_CACHE_HOME时缓存放在$REASONIX_HOME/cache两者都未设置时使用系统缓存目录。有一个特例值得注意跨进程的 workspace 写入锁workspace-leases与 repair 修复锁repair-mutation-locks故意忽略REASONIX_HOME/REASONIX_CACHE_HOME统一落在 OS 用户缓存根目录因为不同隔离实例仍可能打开同一个用户 workspace安全锁必须收敛到同一位置internal/config/paths.go。二、目录内容全览下表列出 Reasonix home及 state/cache 根下的完整目录结构。其中state root默认等于Reasonix home仅当设置REASONIX_STATE_HOME时才不同cache root则遵循 1.4 节的优先级规则。数据路径全局配置Reasonix home/config.toml全局 provider 凭据Reasonix home/.env旧 credentials 导入来源Reasonix home/credentials全局斜杠命令Reasonix home/commands/全局 skillsReasonix home/skills/全局 hooksReasonix home/settings.json远程 SSH 托管 known_hostsReasonix home/remote/known_hosts会话state root/sessions/归档state root/archive/记忆state root/memory/与state root/projects/全局 Desktop Topic 元数据state root/desktop/topic-state-v1.sqlite项目 Desktop Topic 元数据state root/projects/workspace slug/desktop/topic-state-v1.sqlite可丢弃的会话 Catalogcache root/session-catalog/v6.sqlite可丢弃的 Task Catalogcache root/task-catalog/v1.sqlite几个细节需要展开说明1远程 SSH known_hosts 由 Reasonix 托管。路径解析在 internal/config/paths.goReasonix home/remote/known_hosts记录 TOFU首次信任接受的主机公钥用户自己的~/.ssh/known_hosts只读不写。2Desktop Topic 元数据以 SQLite 为权威存储。Desktop Topic 的标题、标题来源、创建时间和自动标题状态以这些 SQLite 文件为权威存储。首次访问时Desktop 会导入项目.reasonix/目录或全局 Reasonix 目录中的旧desktop-topic-*.json检测到旧文件的 scope 会继续镜像旧格式以支持降级全新 scope 不会创建这些 JSON。旧文件不会被删除项目本地 settings、skills、commands、attachments 以及reasonix.toml均不受影响。路径实现在 internal/config/paths.go全局 Topic 直接在 state root 下项目 Topic 通过WorkspaceSlug将绝对 workspace 路径压平为目录名Windows 上折叠大小写定位。3会话 Catalog 与 Task Catalog 是可重建的查询投影不是用户数据。JSONL、event log、metadata sidecar 和desktop-projects.json仍是权威数据Task snapshot 和 event log 也仍是权威数据。删除缓存不会丢失任何用户数据。详见 Session Catalog and Desktop Startup 与 Task Catalog。4全局用户配置文件名是config.toml项目本地配置文件仍叫reasonix.toml。如果有人说“全局 reasonix.toml”通常指的是Reasonix home/config.toml。这条约定在文档中有明确说明也与 internal/config/paths.go 中SourcePathForRoot的解析顺序先项目reasonix.toml再全局 config一致。三、全局config.toml详解Reasonix home/config.toml存放 CLI 与桌面端共用的非密钥配置可以包含 Reasonix 写入用户配置的 provider、plugin、UI、desktop、tool、skill、sandbox、bot 和 agent 设置。Provider 条目只保存api_key_env里的凭据变量名不保存真实密钥值——密钥值属于全局.env见第四节。3.1 完整示例与字段说明以下是文档给出的完整示例已补充注释config_version 1 default_model deepseek/deepseek-v4-flash language zh credentials_store auto # 旧兼容字段provider key 保存在 .env [ui] theme auto cursor_shape bar # CLI/TUI 输入光标underline|block|bar show_turn_usage false # 隐藏 TUI 每轮 token/费用回执默认 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是旧兼容字段源码 internal/config/credentials.go 将其归一化为auto/keyring/file三种模式但当前 provider key 统一保存在.env因此该字段对凭据的实际位置不再起决定作用。[ui].cursor_shape只影响 CLI/TUI 的输入框默认值bar清晰可见同时不会覆盖 CJK 双宽字符如果偏好其它形状可以设为block或underline。[ui].show_turn_usage false会隐藏 TUI transcript 中每次模型请求完成后的 token 与费用回执统计和运行中状态仍正常更新。默认值为true。不要把 API key 的真实值写进config.toml。这个文件是普通配置可以查看、编辑、迁移也可以在常规脱敏后用于诊断。3.2 凭据变量的进程隔离文档强调了一个重要的安全边界已保存的 provider 与 bot 凭据变量不会进入任何由模型控制的子进程环境。Reasonix 的文件读取工具、受沙盒保护的 shell 命令和 MCP server 也无法读取全局凭据.env项目自身的普通.env可见性保持不变。Windows 的 shell 命令仍不具备 OS 级沙箱详见《使用指南》因此只应为可信任务批准 shell 权限。源码层面的佐证internal/config/credentials.go 中CredentialEnvNames()会同时收集配置引用的凭据名和.env中已存在但配置不再引用的陈旧条目目的是让这些名字同样排除在子进程环境之外避免被模型控制的进程读取。四、全局.envprovider 凭据的唯一运行时来源Reasonix home/.env是 Reasonix 保存的 provider API key 的唯一运行时来源。setup 向导、桌面端设置页、CLI 缺 key 提示以及删除 provider key 的操作都会通过同一套凭据 helperinternal/config/credentials.go 中的StoreCredentialLines/SetCredential/RemoveCredential等读写这个文件。4.1 文件结构DEEPSEEK_API_KEYsk-... GEMINI_API_KEY... ANTHROPIC_API_KEY... # reasonix-cleared OLD_API_KEY4.2 读写规则每行一个KEYvalue空行和#注释会被忽略读取时接受export KEYvalue和带引号的值Reasonix 写入时会拒绝多行值key 必须是类似DEEPSEEK_API_KEY的 shell 风格变量名源码isCredentialKey校验见 internal/config/credentials.go# reasonix-cleared KEY是删除 key 后写入的非密钥标记用来防止旧存储把它静默迁回实现见removeCredentialFromFileinternal/config/credentials.go在操作系统支持的情况下Reasonix 会用受限权限写入该文件源码中目录0700、文件0600见 internal/config/credentials.go。写入采用「临时文件 原子替换」策略避免半写入损坏凭据文件同时通过进程内互斥锁与路径派生的 advisory 文件锁串行化所有凭据写事务internal/config/credentials.go桌面窗口、CLI 进程与后台 catalog 保存可以共享同一个 compare-and-apply 边界。SetCredentialIfRevisioninternal/config/credentials.go更进一步只有凭据文件仍处于期望的 SHA-256 revision 时才写入防止过期设置页覆盖其它进程刚保存的凭据。4.3 凭据解析优先级不再有 fallbackProvider 请求只会从全局.env解析 key。以下来源都不再作为运行时 provider key fallback项目.envhome.env继承的 shell 环境变量旧credentials文件系统 keyring边界规则项目.env、home.env和继承的 shell 环境变量不会自动导入到全局凭据文件旧credentials文件和旧 keyring 条目只在全局.env缺少对应 key 时作为非破坏性迁移来源读取项目.env仍作为当前 workspace 范围内的非 provider 变量展开来源例如 MCP/plugin 的 env、headers、URL、command 和 args 中的${VAR}这些值不会写入进程环境REASONIX_HOME、REASONIX_STATE_HOME、XDG_CONFIG_HOME等 Reasonix 控制变量也会被忽略。五、自定义 provider 的api_key_env命名规则通过桌面端设置或reasonix setup添加自定义 provider 时Reasonix 会把生成的api_key_env保存到config.toml并把真实密钥值写入全局.env中同名的 key。生成结果是稳定的因此同一个 provider 重启后仍会读取同一个凭据槽位。5.1 默认命名规则Reasonix 会根据 provider 名称生成默认 env 名源码实现在 internal/cli/cli.go能规范化成 ASCII 的名称会得到可读的 env 名例如LOCAL_GATEWAY_API_KEY名称全部由中文等非 ASCII 字符组成时生成带稳定 hash 后缀的名称例如CUSTOM_d39b9067_API_KEY避免多个中文 provider 都共用CUSTOM_API_KEY名称以数字开头时添加CUSTOM_前缀保证 env 名合法例如9router生成CUSTOM_9ROUTER_API_KEY。5.2 CLI 向导的命名流程CLI 的自定义 provider 向导会先根据 base URL 生成 provider 名称再套用同一套 provider-name 规则。providerSluginternal/cli/cli.go会把 URL 主机名压平成 slughttps://token.sensenova.cn/v1→ provider 名custom-token-sensenova-cn默认 key env 是CUSTOM_TOKEN_SENSENOVA_CN_API_KEY直接回车接受默认值如果你确实想让多个 provider 共用一个凭据也可以手动输入CUSTOM_API_KEY或其他自定义 env 名。5.3 升级兼容性升级时不会自动改写已有配置旧配置中已经使用CUSTOM_API_KEY的自定义 provider 会继续读取这个 key若多个旧自定义 provider 已经意外共用了CUSTOM_API_KEY需要手动把各自的api_key_env改成不同名称并重新保存对应的 API key。源码中filterStaleCustomEntriesinternal/cli/cli.go还会识别旧版向导写入的Namecustom/Nameanthropic的陈旧条目并剔除避免与新版 host-derived slug 名称冲突。六、自定义 provider 的端点 URLrequest_url与models_url桌面端自定义 provider 表单把「API 地址」作为完整请求地址写入request_urlReasonix 不会追加或改写路径。要点已有 TOML 配置不会被重新解释旧chat_url继续保持原来的OpenAI 专用行为Anthropic 和 Responses 仍会根据base_url推导请求路径只有用户在新版桌面端明确保存该 provider 后才会写入并启用request_url保存 OpenAI-compatible provider 时还会把完整地址同步到旧chat_url使旧版本继续使用同一请求目标旧版本无法识别 Anthropic 或 Responses 的任意自定义请求路径模型发现需要单独地址时可设置models_url否则 Reasonix 会继续从base_url推测模型发现地址。七、配置优先级运行时配置按下面顺序解析命令行参数 项目 ./reasonix.toml 全局 Reasonix home/config.toml 兼容读取的旧全局配置 内置默认值写配置时始终写入新的全局路径macOS/Linux: ~/.reasonix/config.toml Windows: %APPDATA%\reasonix\config.toml这一顺序在源码中有对应实现SourcePathForRootinternal/config/paths.go优先返回项目reasonix.toml其次返回用户全局配置而userConfigLoadPathinternal/config/paths.go在全局路径不存在时会依次回落读取 legacy OS app-support 路径与 legacy XDG 路径。八、旧路径迁移v1.8.1 起从v1.8.1开始Reasonix 启动时会在第一次加载配置前自动检查旧路径。迁移是同步、一次性、非破坏性的旧文件会被复制或转换到 Reasonix home原文件保留。8.1 自动迁移的旧配置来源~/Library/Application Support/reasonix/config.toml ~/.config/reasonix/config.toml ~/.reasonix/reasonix.toml ~/.reasonix/config.json对应源码实现legacy OS 路径legacyOSSupportDirinternal/config/paths.go即os.UserConfigDir()/reasonixlegacy XDG 路径legacyXDGConfigPathsinternal/config/paths.go覆盖$XDG_CONFIG_HOME/reasonix/config.toml与~/.config/reasonix/config.toml迁移入口MigrateLegacyIfNeededinternal/config/migrate.go先检查 v1 时代 TOML再检查 v0.5/v0.x 时代的~/.reasonix/config.json含 JSON 迁移到 TOML、旧 API key 写入全局.env等逻辑绝不修改或删除旧文件若新全局配置已存在则跳过。旧 credentials、memory 文件和 sessions 也会在新目标不存在时导入到 Reasonix home。旧 provider key 只会在Reasonix home/.env尚未包含同名 key 时复制进去源码storeCredentialIfAbsentAndNotClearedinternal/config/credentials.go同时检查「已存在」与「已被 reasonix-cleared 标记」两种状态。若新的全局配置已经存在则新配置优先旧配置只作为兼容 fallback 保留。8.2 v1.9.1 起的 MCP 配置补齐从v1.9.1开始Reasonix 还会在升级时把已知旧路径、legacyconfig.json、桌面端已登记项目和恢复 tabs 对应项目里的 MCP 配置汇总补齐到全局Reasonix home/config.toml。规则已有的全局[[plugins]]按名称优先不会被旧配置或项目配置覆盖源文件会保留不变该补齐会写入一次性 marker避免用户之后主动删除某个全局 MCP 时又被旧项目配置反复恢复。九、手动补救迁移/migrate命令如果 Reasonix 已经创建了新的 home 目录但当时旧数据还不在可扫描路径里或者先打开了桌面端导致自动迁移没有把旧路径数据补齐可以在任一前端运行补救命令在CLI TUI中把/migrate输入到聊天输入框在桌面端中把同一个命令输入到 composer。9.1 执行流程与进度提示命令会显示进度提示检查旧配置和 credentials扫描已知旧 memory 位置扫描已知旧 sessions 目录导入尚未迁移过的 memory 文件和 sessions输出最终汇总。对应源码 internal/migration/migration.goRunLegacyRescue依次执行配置迁移、memory 扫描、session 扫描并通过 event sink 输出进度通知。需要注意设置REASONIX_HOME时/migrate的隐式 legacy 迁移会被跳过internal/migration/migration.go。9.2 显式指定旧目录/migrate --from如果旧 v0.x sessions 不在已知旧路径里例如 Windows v0.52 安装时选择了自定义安装/数据目录可以显式指定旧目录/migrate --from D:\OldReasonix要点对应源码RunLegacySessionImportFrominternal/migration/migration.go显式形式只导入 sessions路径可以是旧安装目录、.reasonix/数据目录或者sessions目录本身Reasonix 会在该根目录下检查常见布局sessions/、.reasonix/sessions/、reasonix/sessions/以及根目录本身并使用按来源目录区分的 marker因此之前已经运行过普通/migrate也不会挡住这次后补导入参数解析支持/migrate --from path与/migrate --frompath两种写法带引号路径会被去引号internal/migration/migration.go。9.3 补救命令的非破坏性保证该补救命令仍然是非破坏性的不会覆盖已有的Reasonix home/config.toml如果新配置已经存在需要手动把旧配置里缺失的设置复制过去旧 memory 文件只会在目标文件不存在时复制源码copyFileIfMissing使用O_EXCL创建internal/migration/migration.go尊重 session 导入 marker已经迁移过、之后又被用户删除的会话不会在后续/migrate中被重新恢复。9.4 版本限制自动迁移从v1.8.1开始/migrate只存在于包含该命令的 Go 版 Reasonix 构建中。如果 Reasonix 提示unknown command请先升级后再运行legacy0.xTypeScript 线没有这个命令普通/migrate只会重新扫描上面列出的旧路径。只有确认某个目录是 v0.x session 来源时才使用/migrate --from path它不是备份恢复工具或降级导入工具。十、常见问题与最佳实践Q1为什么设置REASONIX_HOME后看不到旧数据因为REASONIX_HOME触发完整自包含模式Legacy 迁移、OS home 约定目录扫描以及 fallback 路径都会跳过。如果你需要的是「便携安装 迁移旧数据」应在迁移完成后再切换到REASONIX_HOME或在非隔离模式下先跑一次/migrate。Q2为什么项目里的.env明明有DEEPSEEK_API_KEYReasonix 却不读这是设计行为provider 请求只从全局Reasonix home/.env解析 key。项目.env只作为 workspace 范围内的非 provider 变量如${VAR}展开来源。Q3不小心删除了 provider key怎么防止旧存储把它迁回删除操作会写入# reasonix-cleared KEY标记storeCredentialIfAbsentAndNotCleared检测到该标记后会拒绝从旧 keyring/credentials 文件回填。Q4多个旧自定义 provider 共用了CUSTOM_API_KEY怎么办升级不会自动改写配置需要手动把各自的api_key_env改成不同名称并在桌面端设置页或reasonix setup中重新保存对应的 API key。实践建议定期备份Reasonix home/config.toml与Reasonix home/.env注意.env是敏感文件备份需加密或放入密钥管理迁移完成后保留旧目录迁移本身不会删除确认无问题后再自行归档排查配置问题时先reasonix setup或直接查看Reasonix home/config.toml再对照本文的优先级顺序定位生效来源。参考与延伸阅读官方文档配置路径本文主体来源路径解析核心实现internal/config/paths.go凭据存储与解析internal/config/credentials.go自动迁移入口internal/config/migrate.go/migrate补救命令internal/migration/migration.go自定义 provider 命名与向导internal/cli/cli.go会话 Catalog 与桌面启动Session Catalog and Desktop StartupTask CatalogTask Catalog使用指南GUIDE【免费下载链接】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），仅供参考
Reasonix 配置路径与凭据体系完全指南：Home 目录、config.toml、.env 与旧版本迁移
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 homeCLI 与桌面端共用这一套路径解析、凭据存储与迁移机制。本文基于官方文档 docs/CONFIG_PATHS.zh-CN.md并结合仓库源码internal/config/paths.go、internal/config/credentials.go、internal/migration/migration.go 等展开讲解。读完本文你将掌握Reasonix home 在 macOS/Linux/Windows 上的精确位置、REASONIX_HOME/REASONIX_STATE_HOME/REASONIX_CACHE_HOME三个覆盖变量的语义、全局config.toml与全局.env的职责边界与完整配置写法、自定义 provider 的api_key_env命名规则以及从 v1.8.1 之前旧路径自动迁移和/migrate手动补救的完整操作流程。一、Reasonix Home全局配置与状态的唯一入口1.1 各平台的默认位置CLI 与桌面端共享同一个全局目录默认位置随平台不同平台Reasonix homemacOS~/.reasonixLinux~/.reasonixWindows%APPDATA%\reasonix从源码 internal/config/paths.go 可以确认这一解析顺序非 Windows 平台优先取~/.reasonixWindows 优先取%APPDATA%\reasonix即os.UserConfigDir()/reasonix当%APPDATA%不可用时回退到%USERPROFILE%\AppData\Roaming\reasonix。1.2 REASONIX_HOME完整自包含模式可以通过设置环境变量REASONIX_HOME覆盖 Reasonix home官方定位是测试、CI 或便携安装场景普通用户通常不需要设置。设置REASONIX_HOME后运行时进入完整自包含模式配置、状态、缓存和数据全部位于该目录树下互不干扰Legacy 迁移、OS home 约定目录扫描以及其他 fallback 路径全部跳过避免从系统级正式安装带入或写回数据。源码中的IsolatedHomeDir()internal/config/paths.go就是这一隔离机制的实现只要REASONIX_HOME被显式设置迁移逻辑internal/config/migrate.go与/migrate补救命令internal/migration/migration.go都会直接短路跳过。另外注意 internal/config/paths.go 中cleanEnvDir的实现细节REASONIX_HOME支持~与~/xxx写法会被展开为 home 目录、支持${VAR}展开且相对路径会被转为绝对路径路径末尾会被清理。1.3 REASONIX_STATE_HOME仅移动运行状态高级测试或便携安装还可以设置REASONIX_STATE_HOME用于移动sessions、archive、memory等运行状态。需要注意的边界它不会移动全局配置或 provider 凭据这些仍然位于REASONIX_HOME或默认 home下如果旧版本曾把 provider key 写到REASONIX_STATE_HOME/.envReasonix 会在Reasonix home/.env缺少对应 key 时非破坏性导入。源码中userSupportDir()internal/config/paths.go即 state root 的实现设置REASONIX_STATE_HOME时直接返回该目录否则回落到 Reasonix home。SessionDir、ArchiveDir、StatsDir、MemoryUserDirinternal/config/paths.go 与 L544-L546都基于这个 state root 展开。1.4 REASONIX_CACHE_HOME缓存根目录缓存是可丢弃数据默认放在系统缓存目录macOS~/Library/Caches/reasonixLinux$XDG_CACHE_HOME/reasonix或~/.cache/reasonixWindows%LOCALAPPDATA%\reasonix\cache可通过REASONIX_CACHE_HOME覆盖缓存根目录。优先级规则见 internal/config/paths.goREASONIX_CACHE_HOME优先级最高设置REASONIX_HOME且未设置REASONIX_CACHE_HOME时缓存放在$REASONIX_HOME/cache两者都未设置时使用系统缓存目录。有一个特例值得注意跨进程的 workspace 写入锁workspace-leases与 repair 修复锁repair-mutation-locks故意忽略REASONIX_HOME/REASONIX_CACHE_HOME统一落在 OS 用户缓存根目录因为不同隔离实例仍可能打开同一个用户 workspace安全锁必须收敛到同一位置internal/config/paths.go。二、目录内容全览下表列出 Reasonix home及 state/cache 根下的完整目录结构。其中state root默认等于Reasonix home仅当设置REASONIX_STATE_HOME时才不同cache root则遵循 1.4 节的优先级规则。数据路径全局配置Reasonix home/config.toml全局 provider 凭据Reasonix home/.env旧 credentials 导入来源Reasonix home/credentials全局斜杠命令Reasonix home/commands/全局 skillsReasonix home/skills/全局 hooksReasonix home/settings.json远程 SSH 托管 known_hostsReasonix home/remote/known_hosts会话state root/sessions/归档state root/archive/记忆state root/memory/与state root/projects/全局 Desktop Topic 元数据state root/desktop/topic-state-v1.sqlite项目 Desktop Topic 元数据state root/projects/workspace slug/desktop/topic-state-v1.sqlite可丢弃的会话 Catalogcache root/session-catalog/v6.sqlite可丢弃的 Task Catalogcache root/task-catalog/v1.sqlite几个细节需要展开说明1远程 SSH known_hosts 由 Reasonix 托管。路径解析在 internal/config/paths.goReasonix home/remote/known_hosts记录 TOFU首次信任接受的主机公钥用户自己的~/.ssh/known_hosts只读不写。2Desktop Topic 元数据以 SQLite 为权威存储。Desktop Topic 的标题、标题来源、创建时间和自动标题状态以这些 SQLite 文件为权威存储。首次访问时Desktop 会导入项目.reasonix/目录或全局 Reasonix 目录中的旧desktop-topic-*.json检测到旧文件的 scope 会继续镜像旧格式以支持降级全新 scope 不会创建这些 JSON。旧文件不会被删除项目本地 settings、skills、commands、attachments 以及reasonix.toml均不受影响。路径实现在 internal/config/paths.go全局 Topic 直接在 state root 下项目 Topic 通过WorkspaceSlug将绝对 workspace 路径压平为目录名Windows 上折叠大小写定位。3会话 Catalog 与 Task Catalog 是可重建的查询投影不是用户数据。JSONL、event log、metadata sidecar 和desktop-projects.json仍是权威数据Task snapshot 和 event log 也仍是权威数据。删除缓存不会丢失任何用户数据。详见 Session Catalog and Desktop Startup 与 Task Catalog。4全局用户配置文件名是config.toml项目本地配置文件仍叫reasonix.toml。如果有人说“全局 reasonix.toml”通常指的是Reasonix home/config.toml。这条约定在文档中有明确说明也与 internal/config/paths.go 中SourcePathForRoot的解析顺序先项目reasonix.toml再全局 config一致。三、全局config.toml详解Reasonix home/config.toml存放 CLI 与桌面端共用的非密钥配置可以包含 Reasonix 写入用户配置的 provider、plugin、UI、desktop、tool、skill、sandbox、bot 和 agent 设置。Provider 条目只保存api_key_env里的凭据变量名不保存真实密钥值——密钥值属于全局.env见第四节。3.1 完整示例与字段说明以下是文档给出的完整示例已补充注释config_version 1 default_model deepseek/deepseek-v4-flash language zh credentials_store auto # 旧兼容字段provider key 保存在 .env [ui] theme auto cursor_shape bar # CLI/TUI 输入光标underline|block|bar show_turn_usage false # 隐藏 TUI 每轮 token/费用回执默认 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是旧兼容字段源码 internal/config/credentials.go 将其归一化为auto/keyring/file三种模式但当前 provider key 统一保存在.env因此该字段对凭据的实际位置不再起决定作用。[ui].cursor_shape只影响 CLI/TUI 的输入框默认值bar清晰可见同时不会覆盖 CJK 双宽字符如果偏好其它形状可以设为block或underline。[ui].show_turn_usage false会隐藏 TUI transcript 中每次模型请求完成后的 token 与费用回执统计和运行中状态仍正常更新。默认值为true。不要把 API key 的真实值写进config.toml。这个文件是普通配置可以查看、编辑、迁移也可以在常规脱敏后用于诊断。3.2 凭据变量的进程隔离文档强调了一个重要的安全边界已保存的 provider 与 bot 凭据变量不会进入任何由模型控制的子进程环境。Reasonix 的文件读取工具、受沙盒保护的 shell 命令和 MCP server 也无法读取全局凭据.env项目自身的普通.env可见性保持不变。Windows 的 shell 命令仍不具备 OS 级沙箱详见《使用指南》因此只应为可信任务批准 shell 权限。源码层面的佐证internal/config/credentials.go 中CredentialEnvNames()会同时收集配置引用的凭据名和.env中已存在但配置不再引用的陈旧条目目的是让这些名字同样排除在子进程环境之外避免被模型控制的进程读取。四、全局.envprovider 凭据的唯一运行时来源Reasonix home/.env是 Reasonix 保存的 provider API key 的唯一运行时来源。setup 向导、桌面端设置页、CLI 缺 key 提示以及删除 provider key 的操作都会通过同一套凭据 helperinternal/config/credentials.go 中的StoreCredentialLines/SetCredential/RemoveCredential等读写这个文件。4.1 文件结构DEEPSEEK_API_KEYsk-... GEMINI_API_KEY... ANTHROPIC_API_KEY... # reasonix-cleared OLD_API_KEY4.2 读写规则每行一个KEYvalue空行和#注释会被忽略读取时接受export KEYvalue和带引号的值Reasonix 写入时会拒绝多行值key 必须是类似DEEPSEEK_API_KEY的 shell 风格变量名源码isCredentialKey校验见 internal/config/credentials.go# reasonix-cleared KEY是删除 key 后写入的非密钥标记用来防止旧存储把它静默迁回实现见removeCredentialFromFileinternal/config/credentials.go在操作系统支持的情况下Reasonix 会用受限权限写入该文件源码中目录0700、文件0600见 internal/config/credentials.go。写入采用「临时文件 原子替换」策略避免半写入损坏凭据文件同时通过进程内互斥锁与路径派生的 advisory 文件锁串行化所有凭据写事务internal/config/credentials.go桌面窗口、CLI 进程与后台 catalog 保存可以共享同一个 compare-and-apply 边界。SetCredentialIfRevisioninternal/config/credentials.go更进一步只有凭据文件仍处于期望的 SHA-256 revision 时才写入防止过期设置页覆盖其它进程刚保存的凭据。4.3 凭据解析优先级不再有 fallbackProvider 请求只会从全局.env解析 key。以下来源都不再作为运行时 provider key fallback项目.envhome.env继承的 shell 环境变量旧credentials文件系统 keyring边界规则项目.env、home.env和继承的 shell 环境变量不会自动导入到全局凭据文件旧credentials文件和旧 keyring 条目只在全局.env缺少对应 key 时作为非破坏性迁移来源读取项目.env仍作为当前 workspace 范围内的非 provider 变量展开来源例如 MCP/plugin 的 env、headers、URL、command 和 args 中的${VAR}这些值不会写入进程环境REASONIX_HOME、REASONIX_STATE_HOME、XDG_CONFIG_HOME等 Reasonix 控制变量也会被忽略。五、自定义 provider 的api_key_env命名规则通过桌面端设置或reasonix setup添加自定义 provider 时Reasonix 会把生成的api_key_env保存到config.toml并把真实密钥值写入全局.env中同名的 key。生成结果是稳定的因此同一个 provider 重启后仍会读取同一个凭据槽位。5.1 默认命名规则Reasonix 会根据 provider 名称生成默认 env 名源码实现在 internal/cli/cli.go能规范化成 ASCII 的名称会得到可读的 env 名例如LOCAL_GATEWAY_API_KEY名称全部由中文等非 ASCII 字符组成时生成带稳定 hash 后缀的名称例如CUSTOM_d39b9067_API_KEY避免多个中文 provider 都共用CUSTOM_API_KEY名称以数字开头时添加CUSTOM_前缀保证 env 名合法例如9router生成CUSTOM_9ROUTER_API_KEY。5.2 CLI 向导的命名流程CLI 的自定义 provider 向导会先根据 base URL 生成 provider 名称再套用同一套 provider-name 规则。providerSluginternal/cli/cli.go会把 URL 主机名压平成 slughttps://token.sensenova.cn/v1→ provider 名custom-token-sensenova-cn默认 key env 是CUSTOM_TOKEN_SENSENOVA_CN_API_KEY直接回车接受默认值如果你确实想让多个 provider 共用一个凭据也可以手动输入CUSTOM_API_KEY或其他自定义 env 名。5.3 升级兼容性升级时不会自动改写已有配置旧配置中已经使用CUSTOM_API_KEY的自定义 provider 会继续读取这个 key若多个旧自定义 provider 已经意外共用了CUSTOM_API_KEY需要手动把各自的api_key_env改成不同名称并重新保存对应的 API key。源码中filterStaleCustomEntriesinternal/cli/cli.go还会识别旧版向导写入的Namecustom/Nameanthropic的陈旧条目并剔除避免与新版 host-derived slug 名称冲突。六、自定义 provider 的端点 URLrequest_url与models_url桌面端自定义 provider 表单把「API 地址」作为完整请求地址写入request_urlReasonix 不会追加或改写路径。要点已有 TOML 配置不会被重新解释旧chat_url继续保持原来的OpenAI 专用行为Anthropic 和 Responses 仍会根据base_url推导请求路径只有用户在新版桌面端明确保存该 provider 后才会写入并启用request_url保存 OpenAI-compatible provider 时还会把完整地址同步到旧chat_url使旧版本继续使用同一请求目标旧版本无法识别 Anthropic 或 Responses 的任意自定义请求路径模型发现需要单独地址时可设置models_url否则 Reasonix 会继续从base_url推测模型发现地址。七、配置优先级运行时配置按下面顺序解析命令行参数 项目 ./reasonix.toml 全局 Reasonix home/config.toml 兼容读取的旧全局配置 内置默认值写配置时始终写入新的全局路径macOS/Linux: ~/.reasonix/config.toml Windows: %APPDATA%\reasonix\config.toml这一顺序在源码中有对应实现SourcePathForRootinternal/config/paths.go优先返回项目reasonix.toml其次返回用户全局配置而userConfigLoadPathinternal/config/paths.go在全局路径不存在时会依次回落读取 legacy OS app-support 路径与 legacy XDG 路径。八、旧路径迁移v1.8.1 起从v1.8.1开始Reasonix 启动时会在第一次加载配置前自动检查旧路径。迁移是同步、一次性、非破坏性的旧文件会被复制或转换到 Reasonix home原文件保留。8.1 自动迁移的旧配置来源~/Library/Application Support/reasonix/config.toml ~/.config/reasonix/config.toml ~/.reasonix/reasonix.toml ~/.reasonix/config.json对应源码实现legacy OS 路径legacyOSSupportDirinternal/config/paths.go即os.UserConfigDir()/reasonixlegacy XDG 路径legacyXDGConfigPathsinternal/config/paths.go覆盖$XDG_CONFIG_HOME/reasonix/config.toml与~/.config/reasonix/config.toml迁移入口MigrateLegacyIfNeededinternal/config/migrate.go先检查 v1 时代 TOML再检查 v0.5/v0.x 时代的~/.reasonix/config.json含 JSON 迁移到 TOML、旧 API key 写入全局.env等逻辑绝不修改或删除旧文件若新全局配置已存在则跳过。旧 credentials、memory 文件和 sessions 也会在新目标不存在时导入到 Reasonix home。旧 provider key 只会在Reasonix home/.env尚未包含同名 key 时复制进去源码storeCredentialIfAbsentAndNotClearedinternal/config/credentials.go同时检查「已存在」与「已被 reasonix-cleared 标记」两种状态。若新的全局配置已经存在则新配置优先旧配置只作为兼容 fallback 保留。8.2 v1.9.1 起的 MCP 配置补齐从v1.9.1开始Reasonix 还会在升级时把已知旧路径、legacyconfig.json、桌面端已登记项目和恢复 tabs 对应项目里的 MCP 配置汇总补齐到全局Reasonix home/config.toml。规则已有的全局[[plugins]]按名称优先不会被旧配置或项目配置覆盖源文件会保留不变该补齐会写入一次性 marker避免用户之后主动删除某个全局 MCP 时又被旧项目配置反复恢复。九、手动补救迁移/migrate命令如果 Reasonix 已经创建了新的 home 目录但当时旧数据还不在可扫描路径里或者先打开了桌面端导致自动迁移没有把旧路径数据补齐可以在任一前端运行补救命令在CLI TUI中把/migrate输入到聊天输入框在桌面端中把同一个命令输入到 composer。9.1 执行流程与进度提示命令会显示进度提示检查旧配置和 credentials扫描已知旧 memory 位置扫描已知旧 sessions 目录导入尚未迁移过的 memory 文件和 sessions输出最终汇总。对应源码 internal/migration/migration.goRunLegacyRescue依次执行配置迁移、memory 扫描、session 扫描并通过 event sink 输出进度通知。需要注意设置REASONIX_HOME时/migrate的隐式 legacy 迁移会被跳过internal/migration/migration.go。9.2 显式指定旧目录/migrate --from如果旧 v0.x sessions 不在已知旧路径里例如 Windows v0.52 安装时选择了自定义安装/数据目录可以显式指定旧目录/migrate --from D:\OldReasonix要点对应源码RunLegacySessionImportFrominternal/migration/migration.go显式形式只导入 sessions路径可以是旧安装目录、.reasonix/数据目录或者sessions目录本身Reasonix 会在该根目录下检查常见布局sessions/、.reasonix/sessions/、reasonix/sessions/以及根目录本身并使用按来源目录区分的 marker因此之前已经运行过普通/migrate也不会挡住这次后补导入参数解析支持/migrate --from path与/migrate --frompath两种写法带引号路径会被去引号internal/migration/migration.go。9.3 补救命令的非破坏性保证该补救命令仍然是非破坏性的不会覆盖已有的Reasonix home/config.toml如果新配置已经存在需要手动把旧配置里缺失的设置复制过去旧 memory 文件只会在目标文件不存在时复制源码copyFileIfMissing使用O_EXCL创建internal/migration/migration.go尊重 session 导入 marker已经迁移过、之后又被用户删除的会话不会在后续/migrate中被重新恢复。9.4 版本限制自动迁移从v1.8.1开始/migrate只存在于包含该命令的 Go 版 Reasonix 构建中。如果 Reasonix 提示unknown command请先升级后再运行legacy0.xTypeScript 线没有这个命令普通/migrate只会重新扫描上面列出的旧路径。只有确认某个目录是 v0.x session 来源时才使用/migrate --from path它不是备份恢复工具或降级导入工具。十、常见问题与最佳实践Q1为什么设置REASONIX_HOME后看不到旧数据因为REASONIX_HOME触发完整自包含模式Legacy 迁移、OS home 约定目录扫描以及 fallback 路径都会跳过。如果你需要的是「便携安装 迁移旧数据」应在迁移完成后再切换到REASONIX_HOME或在非隔离模式下先跑一次/migrate。Q2为什么项目里的.env明明有DEEPSEEK_API_KEYReasonix 却不读这是设计行为provider 请求只从全局Reasonix home/.env解析 key。项目.env只作为 workspace 范围内的非 provider 变量如${VAR}展开来源。Q3不小心删除了 provider key怎么防止旧存储把它迁回删除操作会写入# reasonix-cleared KEY标记storeCredentialIfAbsentAndNotCleared检测到该标记后会拒绝从旧 keyring/credentials 文件回填。Q4多个旧自定义 provider 共用了CUSTOM_API_KEY怎么办升级不会自动改写配置需要手动把各自的api_key_env改成不同名称并在桌面端设置页或reasonix setup中重新保存对应的 API key。实践建议定期备份Reasonix home/config.toml与Reasonix home/.env注意.env是敏感文件备份需加密或放入密钥管理迁移完成后保留旧目录迁移本身不会删除确认无问题后再自行归档排查配置问题时先reasonix setup或直接查看Reasonix home/config.toml再对照本文的优先级顺序定位生效来源。参考与延伸阅读官方文档配置路径本文主体来源路径解析核心实现internal/config/paths.go凭据存储与解析internal/config/credentials.go自动迁移入口internal/config/migrate.go/migrate补救命令internal/migration/migration.go自定义 provider 命名与向导internal/cli/cli.go会话 Catalog 与桌面启动Session Catalog and Desktop StartupTask CatalogTask Catalog使用指南GUIDE【免费下载链接】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），仅供参考
