wehub/esengine--deepseek-reasonix
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity
Files
main
esengine--deepseek-reasonix/docs/CONFIG_PATHS.zh-CN.md
T
wehub-resource-sync 6345505628 chore: import upstream snapshot with attribution
2026-07-13 13:00:08 +08:00

10 KiB
Raw Permalink Blame History

配置路径

从 Reasonix v1.8.1 开始，Reasonix 使用一个用户可见的全局目录存放配置和用户状态。CLI 与桌面端共用这个目录。

Reasonix Home

平台 Reasonix home
macOS ~/.reasonix
Linux ~/.reasonix
Windows %APPDATA%\reasonix

可以设置 REASONIX_HOME 覆盖 Reasonix home，主要用于测试、CI 或便携安装。普通用户通常不需要设置。

设置 REASONIX_HOME 后，运行时会变成完整自包含模式：配置、状态、缓存和数据都会位于该目录树下。 Legacy 迁移、OS home 约定目录扫描以及其他 fallback 路径都会跳过，避免从系统级正式安装带入或写回数据。

高级测试或便携安装可以设置 REASONIX_STATE_HOME 来移动 sessions、archive、memory 等运行状态。 它不会移动全局配置或 provider 凭据；这些仍然位于 REASONIX_HOME 下。如果旧版本曾把 provider key 写到 REASONIX_STATE_HOME/.env，Reasonix 会在 <Reasonix home>/.env 缺少对应 key 时非破坏性导入。

目录内容

数据 路径
全局配置 <Reasonix home>/config.toml
全局 provider 凭据 <Reasonix home>/.env
旧 credentials 导入来源 <Reasonix home>/credentials
全局斜杠命令 <Reasonix home>/commands/
全局 skills <Reasonix home>/skills/
全局 hooks <Reasonix home>/settings.json
hooks 信任状态 <Reasonix home>/trust.json
会话 <state root>/sessions/
归档 <state root>/archive/
记忆 <state root>/memory/ 与 <state root>/projects/

<state root> 默认等于 <Reasonix home>；只有设置 REASONIX_STATE_HOME 时才会不同。

全局用户配置文件名是 config.toml。项目本地配置文件仍叫 reasonix.toml。 如果有人说“全局 reasonix.toml”，通常指的是 <Reasonix home>/config.toml。

全局 config.toml

<Reasonix home>/config.toml 存放 CLI 与桌面端共用的非密钥配置。它可以包含 Reasonix 写入用户配置的 provider、plugin、UI、desktop、tool、skill、sandbox、 bot 和 agent 设置。Provider 条目只保存 api_key_env 里的凭据变量名，不保存真实密钥值。

示例：

config_version = 1
default_model = "deepseek/deepseek-v4-flash"
language = "zh"
credentials_store = "auto"   # 旧兼容字段；provider key 保存在 .env

[ui]
theme = "auto"
cursor_shape = "underline"   # CLI/TUI 输入光标：underline|block|bar

[desktop]
provider_access = ["deepseek"]

[agent]
auto_plan = "off"
max_steps = 0

[[providers]]
name        = "deepseek"
kind        = "openai"
base_url    = "https://api.deepseek.com"
models      = ["deepseek-v4-flash", "deepseek-v4-pro"]
default     = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"

[[plugins]]
name    = "example"
command = "example-mcp-server"

不要把 API key 的真实值写进 config.toml。这个文件是普通配置：可以查看、编辑、 迁移，也可以在常规脱敏后用于诊断。密钥值属于下面的全局 .env。

[ui].cursor_shape 只影响 CLI/TUI 的输入框。默认值 underline 用来避免终端块状光标在 CJK 双宽字符上造成视觉覆盖；如果偏好其它形状，可以设为 block 或 bar。

自定义 provider 的 api_key_env 命名

通过桌面端设置或 reasonix setup 添加自定义 provider 时，Reasonix 会把生成的 api_key_env 保存到 config.toml，并把真实密钥值写入全局 .env 中同名的 key。 生成结果是稳定的，因此同一个 provider 重启后仍会读取同一个凭据槽位。

Reasonix 会根据 provider 名称生成默认值。能规范化成 ASCII 的名称会得到可读的 env 名，例如 LOCAL_GATEWAY_API_KEY；如果名称全部由中文等非 ASCII 字符组成，则会 生成带稳定 hash 后缀的名称，例如 CUSTOM_d39b9067_API_KEY，避免多个中文 provider 都共用 CUSTOM_API_KEY。

CLI 的自定义 provider 向导会先根据 base URL 生成 provider 名称，再套用同一套 provider-name 规则。例如 https://token.sensenova.cn/v1 会生成 provider 名 custom-token-sensenova-cn，默认 key env 是 CUSTOM_TOKEN_SENSENOVA_CN_API_KEY。 直接回车会接受这个默认值；如果你确实想让多个 provider 共用一个凭据，也可以手动输入 CUSTOM_API_KEY 或其他自定义 env 名。

升级时不会自动改写已有配置。旧配置中已经使用 CUSTOM_API_KEY 的自定义 provider 会继续 读取这个 key。若多个旧自定义 provider 已经意外共用了 CUSTOM_API_KEY，需要手动把各自的 api_key_env 改成不同名称，并重新保存对应的 API key。

自定义 provider 的端点 URL

自定义 OpenAI-compatible provider 通常只需要在 base_url 中填写 API 端点。 Reasonix 会把聊天请求发送到 base_url + "/chat/completions"，并尝试 /models 和 /v1/models 等模型发现地址。如果网关给的是完整聊天请求 URL，可以设置 chat_url；Reasonix 会直接使用这个地址，不再追加 /chat/completions。如果模型 发现需要使用单独地址，可以设置 models_url。

全局 .env

<Reasonix home>/.env 是 Reasonix 保存的 provider API key 的唯一运行时来源。 setup 向导、桌面端设置页、CLI 缺 key 提示以及删除 provider key 的操作，都会通过同一套凭据 helper 读写这个文件。

结构：

DEEPSEEK_API_KEY=sk-...
GEMINI_API_KEY=...
ANTHROPIC_API_KEY=...
# reasonix-cleared OLD_API_KEY

规则：

  • 每行一个 KEY=value；
  • 空行和 # 注释会被忽略；
  • 读取时接受 export KEY=value 和带引号的值；
  • Reasonix 写入时会拒绝多行值；
  • key 必须是类似 DEEPSEEK_API_KEY 的 shell 风格变量名；
  • # reasonix-cleared KEY 是删除 key 后写入的非密钥标记，用来防止旧存储把它静默迁回；
  • 在操作系统支持的情况下，Reasonix 会用受限权限写入该文件。

Provider 请求只会从这个全局 .env 解析 key。项目 .env、home .env、继承的 shell 环境变量、旧 credentials 文件和系统 keyring 都不再作为运行时 provider key fallback。项目 .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 控制变量也会被忽略。

缓存仍放在系统缓存目录，例如 macOS 的 ~/Library/Caches/reasonix、 Linux 的 $XDG_CACHE_HOME/reasonix 或 ~/.cache/reasonix、Windows 的 %LOCALAPPDATA%\reasonix\cache。可以设置 REASONIX_CACHE_HOME 覆盖缓存根目录。 设置 REASONIX_HOME 后，缓存会放在 $REASONIX_HOME/cache；如果同时设置 REASONIX_CACHE_HOME，后者优先。

配置优先级

运行时配置按下面顺序解析：

命令行参数
> 项目 ./reasonix.toml
> 全局 <Reasonix home>/config.toml
> 兼容读取的旧全局配置
> 内置默认值

写配置时始终写入新的全局路径：

macOS/Linux: ~/.reasonix/config.toml
Windows:     %APPDATA%\reasonix\config.toml

旧路径迁移

从 v1.8.1 开始，Reasonix 启动时会在第一次加载配置前自动检查旧路径。迁移是同步、一次性、非破坏性的：旧文件会被复制或转换到 Reasonix home，原文件保留。

旧配置来源包括：

~/Library/Application Support/reasonix/config.toml
~/.config/reasonix/config.toml
~/.reasonix/reasonix.toml
~/.reasonix/config.json

旧 credentials、memory 文件和 sessions 也会在新目标不存在时导入到 Reasonix home。 旧 provider key 只会在 <Reasonix home>/.env 尚未包含同名 key 时复制进去。若新的全局配置已经存在，则新配置优先；旧配置只作为兼容 fallback 保留。

从 v1.9.1 开始，Reasonix 还会在升级时把已知旧路径、legacy config.json、 桌面端已登记项目和恢复 tabs 对应项目里的 MCP 配置汇总补齐到全局 <Reasonix home>/config.toml。已有的全局 [[plugins]] 按名称优先，不会被旧 配置或项目配置覆盖；源文件会保留不变。该补齐会写入一次性 marker，避免用户之后 主动删除某个全局 MCP 时又被旧项目配置反复恢复。

手动补救迁移

如果 Reasonix 已经创建了新的 home 目录，但当时旧数据还不在可扫描路径里；或者先打开了桌面端，导致自动迁移没有把旧路径数据补齐，可以在任一前端运行补救命令：

/migrate

在 CLI TUI 中，把 /migrate 输入到聊天输入框。在桌面端中，把同一个命令输入到 composer。命令会显示进度提示：

  1. 检查旧配置和 credentials；
  2. 扫描已知旧 memory 位置；
  3. 扫描已知旧 sessions 目录；
  4. 导入尚未迁移过的 memory 文件和 sessions；
  5. 输出最终汇总。

如果旧 v0.x sessions 不在上述已知旧路径里，例如 Windows v0.52 安装时选择了自定义安装/数据目录，可以显式指定旧目录：

/migrate --from "D:\OldReasonix"

显式形式只导入 sessions。这个路径可以是旧安装目录、.reasonix/数据目录，或者 sessions 目录本身；Reasonix 会在该根目录下检查常见布局，并使用按来源目录区分的 marker，因此之前已经运行过普通 /migrate 也不会挡住这次后补导入。

该补救命令仍然是非破坏性的。它不会覆盖已有的 <Reasonix home>/config.toml；如果新配置已经存在，需要手动把旧配置里缺失的设置复制过去。旧 memory 文件只会在目标文件不存在时复制。它也会尊重 session 导入 marker，因此已经迁移过、之后又被用户删除的会话，不会在后续 /migrate 中被重新恢复。

版本限制：

  • 自动迁移从 v1.8.1 开始。
  • /migrate 只存在于包含该命令的 Go 版 Reasonix 构建中。如果 Reasonix 提示 unknown command，请先升级后再运行。
  • legacy 0.x TypeScript 线没有这个命令。
  • 普通 /migrate 只会重新扫描上面列出的旧路径。只有确认某个目录是 v0.x session 来源时，才使用 /migrate --from <path>；它不是备份恢复工具或降级导入工具。
Reference in New Issue View Git Blame Copy Permalink