| 1 | # 配置路径 |
| 2 | |
| 3 | 从 **Reasonix v1.8.1** 开始，Reasonix 使用一个用户可见的全局目录存放配置和用户状态。CLI 与桌面端共用这个目录。 |
| 4 | |
| 5 | ## Reasonix Home |
| 6 | |
| 7 | | 平台 | Reasonix home | |
| 8 | | --- | --- | |
| 9 | | macOS | `~/.reasonix` | |
| 10 | | Linux | `~/.reasonix` | |
| 11 | | Windows | `%APPDATA%\reasonix` | |
| 12 | |
| 13 | 可以设置 `REASONIX_HOME` 覆盖 Reasonix home，主要用于测试、CI 或便携安装。普通用户通常不需要设置。 |
| 14 | |
| 15 | 设置 `REASONIX_HOME` 后，运行时会变成完整自包含模式：配置、状态、缓存和数据都会位于该目录树下。 |
| 16 | Legacy 迁移、OS home 约定目录扫描以及其他 fallback 路径都会跳过，避免从系统级正式安装带入或写回数据。 |
| 17 | |
| 18 | 高级测试或便携安装可以设置 `REASONIX_STATE_HOME` 来移动 sessions、archive、memory 等运行状态。 |
| 19 | 它不会移动全局配置或 provider 凭据；这些仍然位于 `REASONIX_HOME` 下。如果旧版本曾把 provider key |
| 20 | 写到 `REASONIX_STATE_HOME/.env`，Reasonix 会在 `<Reasonix home>/.env` 缺少对应 key 时非破坏性导入。 |
| 21 | |
| 22 | ## 目录内容 |
| 23 | |
| 24 | | 数据 | 路径 | |
| 25 | | --- | --- | |
| 26 | | 全局配置 | `<Reasonix home>/config.toml` | |
| 27 | | 全局 provider 凭据 | `<Reasonix home>/.env` | |
| 28 | | 旧 credentials 导入来源 | `<Reasonix home>/credentials` | |
| 29 | | 全局斜杠命令 | `<Reasonix home>/commands/` | |
| 30 | | 全局 skills | `<Reasonix home>/skills/` | |
| 31 | | 全局 hooks | `<Reasonix home>/settings.json` | |
| 32 | | 远程 SSH 托管 known_hosts | `<Reasonix home>/remote/known_hosts` | |
| 33 | | 会话 | `<state root>/sessions/` | |
| 34 | | 归档 | `<state root>/archive/` | |
| 35 | | 记忆 | `<state root>/memory/` 与 `<state root>/projects/` | |
| 36 | |
| 37 | `<state root>` 默认等于 `<Reasonix home>`；只有设置 `REASONIX_STATE_HOME` |
| 38 | 时才会不同。 |
| 39 | |
| 40 | 全局用户配置文件名是 `config.toml`。项目本地配置文件仍叫 `reasonix.toml`。 |
| 41 | 如果有人说“全局 reasonix.toml”，通常指的是 `<Reasonix home>/config.toml`。 |
| 42 | |
| 43 | ## 全局 `config.toml` |
| 44 | |
| 45 | `<Reasonix home>/config.toml` 存放 CLI 与桌面端共用的非密钥配置。它可以包含 |
| 46 | Reasonix 写入用户配置的 provider、plugin、UI、desktop、tool、skill、sandbox、 |
| 47 | bot 和 agent 设置。Provider 条目只保存 `api_key_env` 里的凭据变量名，不保存真实密钥值。 |
| 48 | |
| 49 | 已保存的 provider 与 bot 凭据变量不会进入任何由模型控制的子进程环境。Reasonix 的 |
| 50 | 文件读取工具、受沙盒保护的 shell 命令和 MCP server 也无法读取全局凭据 `.env`； |
| 51 | 项目自身的普通 `.env` 可见性保持不变。Windows 的 shell 命令仍不具备 OS 级沙箱， |
| 52 | 详见《使用指南》，因此只应为可信任务批准 shell 权限。 |
| 53 | |
| 54 | 示例： |
| 55 | |
| 56 | ```toml |
| 57 | config_version = 1 |
| 58 | default_model = "deepseek/deepseek-v4-flash" |
| 59 | language = "zh" |
| 60 | credentials_store = "auto" # 旧兼容字段；provider key 保存在 .env |
| 61 | |
| 62 | [ui] |
| 63 | theme = "auto" |
| 64 | cursor_shape = "bar" # CLI/TUI 输入光标：underline|block|bar |
| 65 | show_turn_usage = false # 隐藏 TUI 每轮 token/费用回执；默认 true |
| 66 | |
| 67 | [desktop] |
| 68 | provider_access = ["deepseek"] |
| 69 | |
| 70 | [[providers]] |
| 71 | name = "deepseek" |
| 72 | kind = "openai" |
| 73 | base_url = "https://api.deepseek.com" |
| 74 | models = ["deepseek-v4-flash", "deepseek-v4-pro"] |
| 75 | default = "deepseek-v4-flash" |
| 76 | api_key_env = "DEEPSEEK_API_KEY" |
| 77 | |
| 78 | [[plugins]] |
| 79 | name = "example" |
| 80 | command = "example-mcp-server" |
| 81 | ``` |
| 82 | |
| 83 | 不要把 API key 的真实值写进 `config.toml`。这个文件是普通配置：可以查看、编辑、 |
| 84 | 迁移，也可以在常规脱敏后用于诊断。密钥值属于下面的全局 `.env`。 |
| 85 | |
| 86 | `[ui].cursor_shape` 只影响 CLI/TUI 的输入框。默认值 `bar` 清晰可见，同时不会覆盖 |
| 87 | CJK 双宽字符；如果偏好其它形状，可以设为 `block` 或 `underline`。 |
| 88 | |
| 89 | `[ui].show_turn_usage = false` 会隐藏 TUI transcript 中每次模型请求完成后的 token 与 |
| 90 | 费用回执；统计和运行中状态仍正常更新。默认值为 `true`。 |
| 91 | |
| 92 | ### 自定义 provider 的 `api_key_env` 命名 |
| 93 | |
| 94 | 通过桌面端设置或 `reasonix setup` 添加自定义 provider 时，Reasonix 会把生成的 |
| 95 | `api_key_env` 保存到 `config.toml`，并把真实密钥值写入全局 `.env` 中同名的 key。 |
| 96 | 生成结果是稳定的，因此同一个 provider 重启后仍会读取同一个凭据槽位。 |
| 97 | |
| 98 | Reasonix 会根据 provider 名称生成默认值。能规范化成 ASCII 的名称会得到可读的 |
| 99 | env 名，例如 `LOCAL_GATEWAY_API_KEY`；如果名称全部由中文等非 ASCII 字符组成，则会 |
| 100 | 生成带稳定 hash 后缀的名称，例如 `CUSTOM_d39b9067_API_KEY`，避免多个中文 provider |
| 101 | 都共用 `CUSTOM_API_KEY`。如果名称以数字开头，则会添加 `CUSTOM_` 前缀以保证生成的 |
| 102 | 环境变量名合法；例如 `9router` 会生成 `CUSTOM_9ROUTER_API_KEY`。 |
| 103 | |
| 104 | CLI 的自定义 provider 向导会先根据 base URL 生成 provider 名称，再套用同一套 |
| 105 | provider-name 规则。例如 `https://token.sensenova.cn/v1` 会生成 provider 名 |
| 106 | `custom-token-sensenova-cn`，默认 key env 是 `CUSTOM_TOKEN_SENSENOVA_CN_API_KEY`。 |
| 107 | 直接回车会接受这个默认值；如果你确实想让多个 provider 共用一个凭据，也可以手动输入 |
| 108 | `CUSTOM_API_KEY` 或其他自定义 env 名。 |
| 109 | |
| 110 | 升级时不会自动改写已有配置。旧配置中已经使用 `CUSTOM_API_KEY` 的自定义 provider 会继续 |
| 111 | 读取这个 key。若多个旧自定义 provider 已经意外共用了 `CUSTOM_API_KEY`，需要手动把各自的 |
| 112 | `api_key_env` 改成不同名称，并重新保存对应的 API key。 |
| 113 | |
| 114 | ### 自定义 provider 的端点 URL |
| 115 | |
| 116 | 自定义 OpenAI-compatible provider 通常只需要在 `base_url` 中填写 API 端点。 |
| 117 | Reasonix 会把聊天请求发送到 `base_url + "/chat/completions"`，并尝试 `/models` |
| 118 | 和 `/v1/models` 等模型发现地址。如果网关给的是完整聊天请求 URL，可以设置 |
| 119 | `chat_url`；Reasonix 会直接使用这个地址，不再追加 `/chat/completions`。如果模型 |
| 120 | 发现需要使用单独地址，可以设置 `models_url`。 |
| 121 | |
| 122 | ## 全局 `.env` |
| 123 | |
| 124 | `<Reasonix home>/.env` 是 Reasonix 保存的 provider API key 的唯一运行时来源。 |
| 125 | setup 向导、桌面端设置页、CLI 缺 key 提示以及删除 provider key 的操作，都会通过同一套凭据 helper 读写这个文件。 |
| 126 | |
| 127 | 结构： |
| 128 | |
| 129 | ```dotenv |
| 130 | DEEPSEEK_API_KEY=sk-... |
| 131 | GEMINI_API_KEY=... |
| 132 | ANTHROPIC_API_KEY=... |
| 133 | # reasonix-cleared OLD_API_KEY |
| 134 | ``` |
| 135 | |
| 136 | 规则： |
| 137 | |
| 138 | - 每行一个 `KEY=value`； |
| 139 | - 空行和 `#` 注释会被忽略； |
| 140 | - 读取时接受 `export KEY=value` 和带引号的值； |
| 141 | - Reasonix 写入时会拒绝多行值； |
| 142 | - key 必须是类似 `DEEPSEEK_API_KEY` 的 shell 风格变量名； |
| 143 | - `# reasonix-cleared KEY` 是删除 key 后写入的非密钥标记，用来防止旧存储把它静默迁回； |
| 144 | - 在操作系统支持的情况下，Reasonix 会用受限权限写入该文件。 |
| 145 | |
| 146 | Provider 请求只会从这个全局 `.env` 解析 key。项目 `.env`、home `.env`、继承的 shell |
| 147 | 环境变量、旧 `credentials` 文件和系统 keyring 都不再作为运行时 provider key fallback。项目 `.env`、home `.env` 和继承的 shell 环境变量不会自动导入到全局凭据文件。 |
| 148 | 旧 `credentials` 文件和旧 keyring 条目只会在新全局 `.env` 缺少对应 key 时作为非破坏性迁移来源读取。 |
| 149 | 项目 `.env` 仍会作为当前 workspace 范围内的非 provider 变量展开来源，例如 MCP/plugin 的 env、headers、URL、command 和 args 中的 `${VAR}`；这些值不会写入进程环境，`REASONIX_HOME`、`REASONIX_STATE_HOME`、`XDG_CONFIG_HOME` 等 Reasonix 控制变量也会被忽略。 |
| 150 | |
| 151 | 缓存仍放在系统缓存目录，例如 macOS 的 `~/Library/Caches/reasonix`、 |
| 152 | Linux 的 `$XDG_CACHE_HOME/reasonix` 或 `~/.cache/reasonix`、Windows 的 |
| 153 | `%LOCALAPPDATA%\reasonix\cache`。可以设置 `REASONIX_CACHE_HOME` 覆盖缓存根目录。 |
| 154 | 设置 `REASONIX_HOME` 后，缓存会放在 `$REASONIX_HOME/cache`；如果同时设置 |
| 155 | `REASONIX_CACHE_HOME`，后者优先。 |
| 156 | |
| 157 | ## 配置优先级 |
| 158 | |
| 159 | 运行时配置按下面顺序解析： |
| 160 | |
| 161 | ```text |
| 162 | 命令行参数 |
| 163 | > 项目 ./reasonix.toml |
| 164 | > 全局 <Reasonix home>/config.toml |
| 165 | > 兼容读取的旧全局配置 |
| 166 | > 内置默认值 |
| 167 | ``` |
| 168 | |
| 169 | 写配置时始终写入新的全局路径： |
| 170 | |
| 171 | ```text |
| 172 | macOS/Linux: ~/.reasonix/config.toml |
| 173 | Windows: %APPDATA%\reasonix\config.toml |
| 174 | ``` |
| 175 | |
| 176 | ## 旧路径迁移 |
| 177 | |
| 178 | 从 **v1.8.1** 开始，Reasonix 启动时会在第一次加载配置前自动检查旧路径。迁移是同步、一次性、非破坏性的：旧文件会被复制或转换到 Reasonix home，原文件保留。 |
| 179 | |
| 180 | 旧配置来源包括： |
| 181 | |
| 182 | ```text |
| 183 | ~/Library/Application Support/reasonix/config.toml |
| 184 | ~/.config/reasonix/config.toml |
| 185 | ~/.reasonix/reasonix.toml |
| 186 | ~/.reasonix/config.json |
| 187 | ``` |
| 188 | |
| 189 | 旧 credentials、memory 文件和 sessions 也会在新目标不存在时导入到 Reasonix home。 |
| 190 | 旧 provider key 只会在 `<Reasonix home>/.env` 尚未包含同名 key 时复制进去。若新的全局配置已经存在，则新配置优先；旧配置只作为兼容 fallback 保留。 |
| 191 | |
| 192 | 从 **v1.9.1** 开始，Reasonix 还会在升级时把已知旧路径、legacy `config.json`、 |
| 193 | 桌面端已登记项目和恢复 tabs 对应项目里的 MCP 配置汇总补齐到全局 |
| 194 | `<Reasonix home>/config.toml`。已有的全局 `[[plugins]]` 按名称优先，不会被旧 |
| 195 | 配置或项目配置覆盖；源文件会保留不变。该补齐会写入一次性 marker，避免用户之后 |
| 196 | 主动删除某个全局 MCP 时又被旧项目配置反复恢复。 |
| 197 | |
| 198 | ## 手动补救迁移 |
| 199 | |
| 200 | 如果 Reasonix 已经创建了新的 home 目录，但当时旧数据还不在可扫描路径里；或者先打开了桌面端，导致自动迁移没有把旧路径数据补齐，可以在任一前端运行补救命令： |
| 201 | |
| 202 | ```text |
| 203 | /migrate |
| 204 | ``` |
| 205 | |
| 206 | 在 CLI TUI 中，把 `/migrate` 输入到聊天输入框。在桌面端中，把同一个命令输入到 composer。命令会显示进度提示： |
| 207 | |
| 208 | 1. 检查旧配置和 credentials； |
| 209 | 2. 扫描已知旧 memory 位置； |
| 210 | 3. 扫描已知旧 sessions 目录； |
| 211 | 4. 导入尚未迁移过的 memory 文件和 sessions； |
| 212 | 5. 输出最终汇总。 |
| 213 | |
| 214 | 如果旧 v0.x sessions 不在上述已知旧路径里，例如 Windows v0.52 安装时选择了自定义安装/数据目录，可以显式指定旧目录： |
| 215 | |
| 216 | ```text |
| 217 | /migrate --from "D:\OldReasonix" |
| 218 | ``` |
| 219 | |
| 220 | 显式形式只导入 sessions。这个路径可以是旧安装目录、`.reasonix`/数据目录，或者 |
| 221 | `sessions` 目录本身；Reasonix 会在该根目录下检查常见布局，并使用按来源目录区分的 |
| 222 | marker，因此之前已经运行过普通 `/migrate` 也不会挡住这次后补导入。 |
| 223 | |
| 224 | 该补救命令仍然是非破坏性的。它不会覆盖已有的 |
| 225 | `<Reasonix home>/config.toml`；如果新配置已经存在，需要手动把旧配置里缺失的设置复制过去。旧 memory 文件只会在目标文件不存在时复制。它也会尊重 session 导入 marker，因此已经迁移过、之后又被用户删除的会话，不会在后续 `/migrate` 中被重新恢复。 |
| 226 | |
| 227 | 版本限制： |
| 228 | |
| 229 | - 自动迁移从 **v1.8.1** 开始。 |
| 230 | - `/migrate` 只存在于包含该命令的 Go 版 Reasonix 构建中。如果 Reasonix 提示 `unknown command`，请先升级后再运行。 |
| 231 | - legacy `0.x` TypeScript 线没有这个命令。 |
| 232 | - 普通 `/migrate` 只会重新扫描上面列出的旧路径。只有确认某个目录是 v0.x session 来源时，才使用 `/migrate --from <path>`；它不是备份恢复工具或降级导入工具。 |
| 233 |