Documentation文档

Everything you need to install Reasonix, start your first session, configure providers and credentials, and understand why long sessions stay cheap. For the full engineering contract, see the Spec and Guide on GitHub.从安装、第一次会话、provider 与凭据配置,到理解为什么长会话依然便宜——你需要的入口都在这里。完整工程契约见 GitHub 上的 Spec 与 Guide。

CLI / TUICLI / TUI

Install the terminal app with one command on macOS, Linux, Windows, or WSL. reasonix opens the interactive TUI; reasonix run is the headless automation entry.一条命令安装终端应用,支持 macOS、Linux、Windows 或 WSL。reasonix 打开交互式 TUI；reasonix run 用于无界面自动执行。

Desktop app桌面端

Quick start快速上手

First run is minimal — reasonix setup walks you through picking a provider and keys, saving new keys to the configured credential store. Then point Reasonix at a repo and start a session:首次运行很简单——reasonix setup 引导你选择 provider 与密钥,新密钥会保存到配置的凭据存储。然后指向仓库、开始会话:

Then just describe the task:然后直接描述任务:

Run /init when you want project memory, then leave the session running — context is append-only, so every new turn starts from a cache hit instead of a cold start.需要项目记忆时运行 /init,然后让会话持续运行——上下文只追加,每一轮都从缓存命中开始,而不是冷启动。

Configuration配置

Reasonix talks directly to configured OpenAI-compatible providers such as DeepSeek or MiMo with your own API keys. Config files name an environment variable through api_key_env; new keys saved by Reasonix go to the OS credential store when available, with a Reasonix-owned file fallback.Reasonix 使用你自己的 API Key 直连配置好的 OpenAI-compatible provider,例如 DeepSeek 或 MiMo。配置文件通过 api_key_env 指定环境变量；Reasonix 保存的新密钥优先进入系统密钥库,不可用时使用 Reasonix 自己的文件 fallback。

Project .env files are read for compatibility and deliberate per-project overrides, but Reasonix does not write new keys there. Persistent options live in the config file.项目 .env 会被读取,用于兼容旧项目或明确的项目级覆盖,但 Reasonix 不会把新密钥写入那里。持久化选项见配置文件。

Prefix cache前缀缓存

DeepSeek bills cached prefix tokens at a fraction of fresh computation. Most agents waste this: they reorder messages, rewrite summaries mid-session, or inject volatile timestamps — every change invalidates the cache from that point on.DeepSeek 对缓存前缀 token 的计费远低于新计算。多数智能体浪费了这一点:重排消息、会话中改写摘要、注入易变的时间戳——任何改动都会让其后的缓存全部失效。

Reasonix serializes context deterministically and only ever appends. The practical effect: hours-long sessions where 90%+ of every request replays from cache, and input-token cost collapses to ~1/5. See the animated walkthrough on the home page.Reasonix 以确定性方式序列化上下文,并且永远只追加。实际效果:数小时的会话中每次请求 90% 以上从缓存重放,输入 token 成本降到约 1/5。可在首页查看动态演示。

Permissions & sandbox权限与沙箱

Permissions gate each tool call: deny > ask > allow > fallback. Read-only tools generally pass; writers fall back to [permissions] mode. reasonix prompts before fallback writers; reasonix run stays autonomous but still honours deny.权限逐个把关工具调用:deny > ask > allow > 兜底。只读工具通常放行；写工具回退到 [permissions] mode。reasonix 会在 fallback 写操作前询问；reasonix run 自主运行,但仍遵守 deny。

The sandbox is enforcement: file-writers refuse any path outside [sandbox] workspace_root (default: the current dir), resolving symlinks and .. so a link cannot tunnel out. On macOS, bash is jailed by default with the same write roots; other platforms currently fall back to unconfined shell execution. Reads are unrestricted.沙箱负责强制执行:写文件工具拒绝 [sandbox] workspace_root(默认当前目录)之外的任何路径,并解析符号链接与 ..,防止借链接逃逸。macOS 上 bash 默认也会按同一组写入根目录隔离；其他平台目前回退到非隔离 shell 执行。读取不受限。

Plugins (MCP)插件(MCP)

Reasonix is an MCP client. A [[plugins]] entry's type selects the transport: stdio launches a local subprocess, while http connects to a Streamable HTTP server with optional headers expanded from the environment. Tools surface to the model as mcp__<server>__<tool>.Reasonix 是一个 MCP 客户端。[[plugins]] 条目的 type 选择传输方式：stdio 启动本地子进程；http 连接 Streamable HTTP server,可从环境变量展开静态 headers。工具以 mcp__<server>__<tool> 呈现给模型。

MCP prompts also become slash commands such as /mcp__server__prompt, and MCP resources can be referenced with @server:uri. Enabled servers connect in the background after a session starts; use /mcp or the desktop MCP panel to inspect, refresh, reconnect, or disable servers. Already have an .mcp.json? Put it in the project root; Reasonix reads the Claude Code mcpServers schema as-is and lets reasonix.toml win on name collisions.MCP prompts 也会变成 /mcp__server__prompt 这样的斜杠命令,MCP resources 可通过 @server:uri 引用。启用的 server 会在会话开始后后台连接；用 /mcp 或桌面端 MCP 面板查看、刷新、重连或临时禁用。已有 .mcp.json?放到项目根目录即可；Reasonix 会原样读取 Claude Code 的 mcpServers schema,同名时 reasonix.toml 优先。

Memory & rewind记忆与回退

Reasonix keeps project memory in REASONIX.md or AGENTS.md, and stores approved auto-memory facts under Reasonix home. During turns, read-only history and memory tools retrieve prior sessions, compacted archives, and saved facts on demand instead of injecting noisy dynamic state into the stable prompt prefix.Reasonix 将项目记忆放在 REASONIX.md 或 AGENTS.md,并把经过批准的 auto-memory fact 存在 Reasonix home 下。运行时,只读 history 与 memory 工具按需检索历史会话、压缩归档和已保存事实,而不是把易变状态塞进稳定 prompt 前缀。

Agent-initiated remember and forget always ask for fresh approval, even in YOLO. /memory shows active and archived facts; /forget archives rather than permanently erasing a fact from traceability.模型主动调用 remember 与 forget 时,即使在 YOLO 下也会重新请求批准。/memory 可查看 active 与 archived facts；/forget 会归档而不是永久抹掉可追溯记录。

Rewind is snapshot-based, not git-based. Press double Esc in the CLI, use /rewind, or use the desktop hover control to restore code, conversation, or both from an earlier turn without touching .git.回退基于文件快照,不是 git。CLI 中双击 Esc、使用 /rewind,或在桌面端用户消息上使用 hover 控件,即可从较早 turn 恢复代码、对话或两者,不会触碰 .git。

CLI & slash commands命令行与斜杠命令

Inside a session, slash commands run locally — /help lists them all:会话中,斜杠命令在本地运行——/help 列出全部:

/branch [name] forks the current conversation tip, /switch <id|name> loads another branch, and /clear confirms before discarding unsaved context. Custom commands are Markdown files under .reasonix/commands/ or ~/.reasonix/commands/./branch [name] 从当前会话尖端分叉,/switch <id|name> 加载另一条分支,/clear 会确认后丢弃未保存上下文。自定义命令是 .reasonix/commands/ 或 ~/.reasonix/commands/ 下的 Markdown 文件。

Use @path to inject files or directories, and @server:uri for MCP resources. reasonix config auto-plan off|on and reasonix config reasoning-language auto|zh|en update user defaults from scripts; add --local only for project-local overrides.用 @path 注入文件或目录,用 @server:uri 引入 MCP resource。脚本中可用 reasonix config auto-plan off|on 与 reasonix config reasoning-language auto|zh|en 更新用户级默认值；只有明确需要项目级覆盖时才加 --local。

Config file配置文件

Resolution order: flags > ./reasonix.toml > global config.toml under Reasonix home > compatible legacy config > built-in defaults. Starting with v1.8.1, Reasonix home is ~/.reasonix on macOS/Linux and %APPDATA%\reasonix on Windows; set REASONIX_HOME only for tests, CI, or portable installs.解析顺序:flags > ./reasonix.toml > Reasonix home 下的全局 config.toml > 兼容 legacy config > 内置默认值。从 v1.8.1 起,Reasonix home 在 macOS/Linux 为 ~/.reasonix,Windows 为 %APPDATA%\reasonix；只有测试、CI 或便携安装才需要设置 REASONIX_HOME。

Legacy config, credentials, memory, and sessions are migrated non-destructively when v1.8.1+ starts. If Reasonix was opened before old paths were available, run /migrate from the CLI TUI or desktop composer. For the full schema and every field's contract, see SPEC.md §5.v1.8.1+ 启动时会非破坏性迁移 legacy config、credentials、memory 与 sessions。如果旧路径尚不可用时已经打开过 Reasonix,可在 CLI TUI 或桌面端 composer 中运行 /migrate。完整 schema 与每个字段的契约见 SPEC.md §5。

Desktop & bots桌面端与 Bot

The desktop app shares the same config, credential store, controller, permissions, sandbox, MCP lifecycle, memory, and checkpoint model as the CLI. Desktop-only settings such as shortcuts and bot connections are stored under Reasonix home.桌面端与 CLI 共用同一套 config、凭据存储、controller、权限、沙箱、MCP 生命周期、记忆与 checkpoint 模型。快捷键、Bot 连接等桌面端设置存储在 Reasonix home 下。

From Settings -> Bots, connect Feishu, Lark, or WeChat, then send Reasonix messages from IM. The local desktop runtime handles model calls, tools, approvals, and sandboxing, while IM receives progress, approval cards or text commands, and final results. Headless gateways can be started with reasonix bot start --channels feishu,lark,weixin --dir /path/to/project.在 Settings -> Bots 中连接飞书、Lark 或微信后,即可从 IM 给 Reasonix 发消息。本地桌面运行时负责模型调用、工具、审批和沙箱,IM 侧接收进度、审批卡片或文本命令以及最终结果。也可以用 reasonix bot start --channels feishu,lark,weixin --dir /path/to/project 启动 headless gateway。