从零读懂 reasonix.toml：12 个配置段，一篇讲清楚

之前三篇下来，你应该已经装好了 Reasonix、知道怎么用 Chat 和 Run、也学会了权限设置。

但那个 ~/.config/reasonix/config.toml 文件里，还有一大堆没讲过的配置项。provider 能配几个模型？statusline 能不能显示 Git 分支？多模型协同到底改哪一行？

今天一次性把整个配置文件拆开讲。

一、先搞懂配置加载顺序

Reasonix 的配置有四个层级，优先级从高到低：

命令行 flag（最高）
  ↓
项目目录 ./reasonix.toml（只对本项目生效）
  ↓
用户全局 ~/.config/reasonix/config.toml（所有项目通用）
  ↓
内置默认值（最低）

密钥（API Key） 是个例外——它只从环境变量读取，永远不会写进配置文件。这是安全设计。

这意味着：

• 想全局生效 → 改 ~/.config/reasonix/config.toml
• 只想某个项目特殊设置 → 在项目根目录放一个 ./reasonix.toml，只写你要覆盖的字段就行
• 临时覆盖 → 加命令行 flag

二、完整配置拆解

下面这个是 Reasonix 配置文件的完整结构，我帮你把每一段都标注了：

# ═══════════════════════════════════════════
# 第一部分：全局基本设置
# ═══════════════════════════════════════════

config_version = 2
default_model = "deepseek-flash"
language      = "zh"

这两行是高频修改项，单独拿出来讲。

default_model

default_model = "deepseek-flash"   # 默认模型

在 reasonix chat 或 reasonix run 没有指定 --model 时，用的就是这个模型。

可选值取决于你在 [[providers]] 里配了哪些。Reasonix 出厂预置了四个模型预设：

language

language = "zh"   # 界面和模型回复的语言

留空则自动检测 $LANG 或 $REASONIX_LANG 环境变量。

# ═══════════════════════════════════════════
# 第二部分：界面与通知
# ═══════════════════════════════════════════

[ui]
theme = "auto"           # auto | dark | light
# theme_style = "graphite"  # 8 种配色可选

CLI 终端的主题设置。theme 控制亮/暗色，theme_style 控制配色风格。

8 种配色风格预览：

[desktop]
theme = "dark"           # 桌面端独立主题
# theme_style = "graphite"
close_behavior = "background"  # 关闭按钮行为：quit | background

桌面端的设置。跟 CLI 的 [ui] 是独立的，你可以 CLI 用亮色、桌面端用暗色。

close_behavior 是桌面端特有的——设为 background 时，点关闭按钮只是隐藏到系统托盘，不退出。

[notifications]
enabled = false           # 系统通知总开关
turn_done = true          # AI 完成一轮对话时通知
approval_request = true   # 等待你批准工具调用时通知
ask_request = true        # 等待你回答问题时通知

系统通知，默认关闭。如果你经常在后台跑 Reasonix、切到别的窗口做事，打开这个很有用——AI 需要你的时候会弹系统通知叫你。

# ═══════════════════════════════════════════
# 第三部分：网络与代理
# ═══════════════════════════════════════════

[network]
proxy_mode = "auto"   # auto | env | custom | off
# proxy_url  = "socks5://127.0.0.1:7890"
# no_proxy   = "localhost,127.0.0.1,.local"

[network.proxy]
type = "socks5"   # http | https | socks5 | socks5h
# server = "127.0.0.1"
# port = 7890

如果你在需要代理的环境下使用（比如公司网络或某些地区访问 DeepSeek 不稳定），这里配置代理。

proxy_mode = "auto" 会自动检测环境变量中的代理设置。不够用的话，切到 custom 手动指定。

# ═══════════════════════════════════════════
# 第四部分：Agent 行为控制（核心）
# ═══════════════════════════════════════════

[agent]
max_steps   = 0           # 最大工具调用轮数；0 = 不限
temperature = 0.0         # 输出随机性；0 = 确定，1 = 创意
auto_plan   = "off"       # off | on；自动计划模式
soft_compact_ratio  = 0.5  # 缓存告警水位线
compact_ratio       = 0.8  # 触发上下文压缩
compact_force_ratio = 0.9  # 强制压缩水位线
# planner_model   = "deepseek-pro"  # 双模型协同：规划器
# subagent_model  = "deepseek-pro"  # subagent 默认模型
# subagent_models = { review = "deepseek-pro" }  # 按 skill 单独指定
# output_style    = "explanatory"   # 回复风格

这是配置文件里最重要的段落，我来一个一个说：

max_steps

max_steps = 0   # 0 = 不限

控制 AI 在单次任务中最多能调用几次工具。设为 5 意味着 AI 最多只能执行 5 步操作（读文件、写文件、跑命令等）。

建议：

• 日常开发：保持 0（不限），让 AI 自己判断
• 预算敏感：设 20 或 50，防止 AI 陷入死循环

temperature

temperature = 0.0

控制 AI 输出的随机性：

• 0.0 = 完全确定，每次回答都一样（适合编码）
• 0.5 = 适度创意
• 1.0 = 高度随机（适合写文案、头脑风暴）

auto_plan

auto_plan = "off"   # off 表示手动开启计划模式

这是第三篇讲过的计划模式开关：

• "off"：默认手动，需要时你在 Chat 里输入 /plan
• "on"：AI 判断复杂任务时自动进入计划模式

上下文压缩

soft_compact_ratio  = 0.5   # 用到 50% 上下文窗口时提醒
compact_ratio       = 0.8   # 用到 80% 时执行压缩
compact_force_ratio = 0.9   # 用到 90% 时强制压缩

Reasonix 会在上下文快满时，自动把早期对话压缩成一段摘要。这三个参数控制压缩的触发时机：

• 达到 compact_ratio（80%）→ 执行一次压缩
• 同时，每次压缩都会重置缓存，所以不要设得太激进
• 默认值已经经过调优，建议保持不动

双模型协同预告

# planner_model = "deepseek-pro"   # 规划器模型

这里只露个脸，告诉读者有这个东西。会在第 09 篇高阶篇专门讲。

output_style

# output_style = "explanatory"   # explanatory | learning | concise | custom

控制 AI 回复的风格：

• explanatory：详细解释每一步（适合教学）
• learning：以教学口吻输出（适合新手）
• concise：只说结论（适合老手）
• custom：自定义风格

# ═══════════════════════════════════════════
# 第五部分：模型提供商配置（最常用）
# ═══════════════════════════════════════════

[[providers]]
name        = "deepseek-flash"
kind        = "openai"
base_url    = "https://api.deepseek.com"
models      = ["deepseek-v4-flash"]
default     = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
balance_url = "https://api.deepseek.com/user/balance"
context_window = 1000000
price       = { cache_hit = 0.02, input = 1, output = 2, currency = "¥" }

这是配置文件里你最可能需要动手改的段落。

添加自己的模型

如果你想用其他 OpenAI 兼容的模型（比如通义千问、智谱 GLM、Ollama 本地模型），加一段新的 [[providers]] 就行：

# 示例：接入阿里通义千问
[[providers]]
name        = "qwen"
kind        = "openai"
base_url    = "https://dashscope.aliyuncs.com/compatible-mode/v1"
model       = "qwen-plus"
api_key_env = "QWEN_API_KEY"
context_window = 1000000

# 示例：接入本地 Ollama
[[providers]]
name        = "ollama"
kind        = "openai"
base_url    = "http://localhost:11434/v1"
model       = "llama3"
api_key_env = "OLLAMA_API_KEY"   # Ollama 通常不需要 key，随便填

关键字段说明：

[[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"

这样同一个 API Key 能同时用 flash 和 pro 两个模型，不用写两段重复配置。

# ═══════════════════════════════════════════
# 第六部分：工具设置
# ═══════════════════════════════════════════

[tools]
enabled = []   # 空 = 启用所有内置工具
bash_timeout_seconds = 120   # 命令超时

enabled

enabled = []   # 空 = 全部启用

如果你想禁用某些工具，可以在这里列出只想要的那几个。比如只想要读写文件和搜索，不想让 AI 执行 bash：

[tools]
enabled = ["read_file", "write_file", "edit_file", "ls", "glob", "grep"]

Reasonix 目前内置了这些工具：read_file、write_file、edit_file、multi_edit、bash、ls、glob、grep、web_fetch、task、todo_write、ask、notebook_edit。

bash_timeout_seconds

bash_timeout_seconds = 120   # 命令超时时间（秒）

AI 执行的每个 bash 命令的超时时间。如果 AI 跑了一个死循环或者编译大型项目，超过这个时间会被自动中断。

# ═══════════════════════════════════════════
# 第七部分：代码理解（CodeGraph）
# ═══════════════════════════════════════════

[codegraph]
enabled      = false
auto_install = true

CodeGraph 是 Reasonix 内置的代码智能引擎——用 tree-sitter 解析代码，构建符号表和调用图。AI 可以问"这个函数在哪里定义的？"、"谁调用了这个方法？"

不需要 embedding 服务，没有 API 成本——纯本地分析。

默认关闭。打开方式：

[codegraph]
enabled = true

首次启用会自动下载运行时（约 10MB）。打开后 AI 就多了两个工具：codegraph_symbols 和 codegraph_callers。

# ═══════════════════════════════════════════
# 第八部分：Skills 技能
# ═══════════════════════════════════════════

[skills]
# paths = ["~/my-skills", "../shared/skills"]
# excluded_paths = ["~/.agents/skills"]
# disabled_skills = ["review"]
# max_depth = 3

Skills 是 Reasonix 的可复用技能包——用 Markdown 写的 AI 工作流模板。项目会在第 07 篇专门讲。

[skills]
paths = ["~/my-skills"]             # 额外技能目录
disabled_skills = ["review"]         # 暂时禁用某个技能

# ═══════════════════════════════════════════
# 第九部分：状态栏自定义
# ═══════════════════════════════════════════

[statusline]
# command = "my-statusline.sh"

这是之前有读者问过的状态栏定制。默认状态栏显示的是模型名、缓存命中率、Session 时长、花费。

如果你想显示 Git 分支、当前路径、或者任何自定义信息，可以写一个脚本：

#!/bin/bash
# ~/.config/reasonix/statusline.sh
# 从 stdin 接收 JSON：{"model":"...","contextUsed":...,"contextWindow":...,"cwd":"..."}

read input
# 用 jq 解析输入，拼出你想要的状态栏
model=$(echo "$input" | jq -r '.model')
cwd=$(echo "$input" | jq -r '.cwd')
branch=$(git -C "$cwd" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")

echo "📁 $(basename $cwd) | 🌿 $branch | 🤖 $model"

然后配置：

[statusline]
command = "bash ~/.config/reasonix/statusline.sh"

效果就是底部的状态栏变成了你自定义的内容。

三、配置实战：搭建你自己的配置

模板一：新手推荐（直接复制使用）

config_version = 2
default_model = "deepseek-flash"
language = "zh"

[ui]
theme = "auto"
theme_style = "aurora"

[agent]
max_steps = 0
temperature = 0.0
auto_plan = "off"

[[providers]]
name        = "deepseek-flash"
kind        = "openai"
base_url    = "https://api.deepseek.com"
model       = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
balance_url = "https://api.deepseek.com/user/balance"
context_window = 1000000
price       = { cache_hit = 0.02, input = 1, output = 2, currency = "¥" }

[permissions]
mode = "ask"
deny = ["bash(rm -rf*)", "bash(sudo*)", "bash(shutdown*)"]

模板二：多模型进阶（同时用 DeepSeek + MiMo + 本地）

config_version = 2
default_model = "deepseek-flash"
language = "zh"

[[providers]]
name        = "deepseek-flash"
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"
context_window = 1000000
price       = { cache_hit = 0.02, input = 1, output = 2, currency = "¥" }

[[providers]]
name        = "mimo-pro"
kind        = "openai"
base_url    = "https://api.xiaomimimo.com/v1"
model       = "mimo-v2.5-pro"
api_key_env = "MIMO_API_KEY"

[[providers]]
name        = "ollama"
kind        = "openai"
base_url    = "http://localhost:11434/v1"
model       = "codellama"
api_key_env = "FAKE_KEY"

这样你就能在 Chat 里用 /model 随时切换模型了。

四、常用操作速查

写在最后

配置文件虽然字段多，但日常你只需要关注这几个：

🔜 下一篇预告：MCP 插件生态——给 AI 接上翅膀

Reasonix 最强大的能力之一：通过 MCP 协议接入外部工具。让 AI 搜索网页、查询数据库、调用企业内部 API。而且你在 Claude Code 里配好的 .mcp.json 直接拿过来就能用。

关注我，带你用最少的钱，薅最狠的 AI 羊毛。

📌 互动话题：你配了哪些模型提供商？有没有什么好用的第三方模型推荐？评论区聊聊。