Install, configure, and run coding work locally.安装、配置，并在本地运行编码任务。

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桌面端

macOS quarantine warningmacOS 隔离属性提示

Use this only when Reasonix was downloaded from the official site or GitHub release, moved to /Applications, and macOS still says the app cannot be opened, cannot be verified, or is damaged. This removes the quarantine flag that macOS attaches to downloaded apps.仅在 Reasonix 来自官网或 GitHub Release、已经放入 /Applications,但 macOS 仍提示“无法打开”“无法验证开发者”或“应用已损坏”时使用。它会移除 macOS 给下载应用附加的隔离属性。

Quick start快速上手

First run is minimal — reasonix setup walks you through picking a provider and key, then saves it under Reasonix home. Then point Reasonix at a repo and start a session:首次运行很简单——reasonix setup 引导你选择 provider 并填写密钥,然后保存到 Reasonix home。接着指向仓库、开始会话:

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,然后让会话持续运行——上下文只追加,每一轮都从缓存命中开始,而不是冷启动。

Web frontendWeb 前端

reasonix serve starts the same local Reasonix engine behind a browser UI. Use it when you want a desktop-style surface without installing the desktop app, when running Reasonix on a remote development box through a tunnel, or when you want a shareable view of a live session.reasonix serve 会用同一个本地 Reasonix 引擎启动浏览器 UI。适合不安装桌面端但想用可视化界面、在远程开发机上通过 tunnel 使用,或把当前会话临时共享给浏览器查看。

The default listen address is 127.0.0.1:8787 with auth_mode = "none". Keep that for local-only use. If the server is reachable from another machine, enable auth before sharing the URL.默认监听 127.0.0.1:8787,认证模式是 auth_mode = "none"。这个默认值只适合本机使用；如果其他机器能访问,请先开启认证再分享 URL。

Configuration配置

Reasonix talks directly to configured OpenAI-compatible providers such as DeepSeek or MiMo with your own API keys. Provider config stores only the key name in api_key_env; the actual secret saved by reasonix setup or desktop Settings lives in the global <Reasonix home>/.env.Reasonix 使用你自己的 API Key 直连配置好的 OpenAI-compatible provider,例如 DeepSeek 或 MiMo。Provider 配置只在 api_key_env 里记录密钥名称；通过 reasonix setup 或桌面端设置保存的真实密钥会写入全局 <Reasonix home>/.env。

Project .env files are not provider-key fallbacks. They are only used for workspace-scoped variable expansion in MCP/plugin settings. Persistent options live in the config file.项目 .env 不是 provider key 的 fallback。它只用于 MCP/plugin 配置里的工作区级变量展开。持久化选项见配置文件。

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. Ask is not read-only: an approved writer can still run. The sandbox is the enforced capability boundary. Headless reasonix run defaults to Ask and fails closed when a writer needs approval; use -y, --auto, or --permission-mode auto for intentional unattended writes. [permissions] allow_dynamic_bash = true is an advanced opt-in that lets an Allow fallback cover nested or indirect Bash. Explicit ask and deny rules still apply.权限逐个把关工具调用:deny > ask > allow > 兜底。只读工具通常放行；写工具回退到 [permissions] mode。Ask 不是只读：writer 获得批准后仍会执行；沙箱才是强制能力边界。无界面的 reasonix run 默认使用 Ask，写操作需要审批时会安全拒绝；要显式启用无人值守写入，请使用 -y、--auto 或 --permission-mode auto。高级用户可设置 [permissions] allow_dynamic_bash = true，让 Allow fallback 覆盖嵌套或间接 Bash。显式 ask 与 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. bash = "enforce" jails shell commands when an OS sandbox backend is available (Seatbelt on macOS, bubblewrap on Linux); without one, bash is refused instead of running unconfined. Install the backend or set bash = "off" to explicitly restore the pre-1.16 unconfined behavior.沙箱负责强制执行:写文件工具拒绝 [sandbox] workspace_root(默认当前目录)之外的任何路径,并解析符号链接与 ..,防止借链接逃逸。bash = "enforce" 会在存在 OS 沙箱后端时隔离 shell 命令（macOS Seatbelt、Linux bubblewrap）；没有后端时会拒绝执行 bash，而不是非隔离运行。安装对应后端，或显式设置 bash = "off" 来恢复 1.16 之前的非隔离行为。

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> 呈现给模型。

Installing an MCP server is the authorization decision, so its tools are directly usable without server-level, per-tool, writer, or destructive approval settings. Repository-declared servers require one exact identity confirmation before startup and ask again only when that identity changes. Explicit global deny rules still win. readOnlyHint and destructiveHint remain internal facts for parallel dispatch, Plan restrictions, strict read-only children, and cached-to-live safety reclassification; schema-only changes refresh the next-session cache without interrupting an authorized call. Plan hard-blocks MCP writer/destructive targets and unauthorized readers; read_only_task / read_only_skill never expose writers.安装 MCP server 本身就是授权决定，安装后工具直接可用，不再需要 server、逐工具、writer 或 destructive 审批设置。仓库声明的 server 只在启动前确认一次精确身份，身份变化时才重新确认；显式全局 deny 仍然优先。readOnlyHint 与 destructiveHint 只作为并行调度、Plan 限制、严格只读子会话和缓存到实时安全分类复核的内部事实；仅 schema 变化会刷新下一会话缓存，不再中断已授权调用。Plan 会硬阻断 MCP writer/destructive 目标和未授权 reader；read_only_task / read_only_skill 完全不暴露 writer。

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 优先。

Editor integration (ACP)编辑器接入（ACP）

Reasonix implements Agent Client Protocol (ACP) v1 as an NDJSON JSON-RPC 2.0 agent over stdio. An ACP-compatible editor or host starts reasonix acp, opens workspace-scoped sessions, and receives streamed messages, tool activity, plans, permission requests, and configuration updates.Reasonix 实现了 Agent Client Protocol（ACP）v1，通过 stdio 提供 NDJSON JSON-RPC 2.0 agent。兼容 ACP 的编辑器或 host 启动 reasonix acp、打开工作区会话，并接收流式消息、工具活动、计划、权限请求和配置更新。

Reasonix also advertises the vendor method _reasonix.io/session/steer through agentCapabilities._meta. A host may call it while session/prompt is active to queue user guidance for the next safe model boundary without cancelling the turn. Clients must discover the method first and treat InvalidRequest as not queued.Reasonix 还会通过 agentCapabilities._meta 声明厂商方法 _reasonix.io/session/steer。Host 可在 session/prompt 活动期间调用它，把用户引导排入下一个安全模型边界，而无需取消当前回合。客户端必须先发现该方法，并把 InvalidRequest 视为“未入队”。

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命令行与斜杠命令

Run reasonix upgrade to update on the saved channel. Use reasonix upgrade preview or reasonix upgrade stable to switch channels, remember the choice globally, and update the same native CLI binary. Fresh and older configs start on Stable; project config cannot change the channel.运行 reasonix upgrade 会按已保存渠道更新。使用 reasonix upgrade preview 或 reasonix upgrade stable 可切换渠道、全局记住选择，并更新同一个原生 CLI 二进制文件。全新和旧版配置默认使用正式版，项目配置不能更改此渠道。

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

Shift+Tab cycles Ask → Auto → Plan, while Ctrl+Y toggles YOLO independently. Use /theme auto|light|dark for the terminal background mode or choose a named accent from bare /theme. Long drafts grow and then scroll inside the composer; wheel events over the transcript continue to scroll the conversation.Shift+Tab 按 Ask → Auto → Plan 循环，Ctrl+Y 独立切换 YOLO。用 /theme auto|light|dark 选择终端背景模式，也可从不带参数的 /theme 中选择命名强调色。长草稿会先增长，超过上限后在输入框内滚动；鼠标位于 transcript 时仍滚动对话。

The responsive footer shows the active permission posture and interaction state first. Wide terminals keep model, effort, and work mode together on the right, with available Git, cache, context, compaction, job, and balance telemetry below. ready means the composer is idle; pickers, approvals, image paste, shell mode, and other interactions replace it. Narrow terminals move or compact complete groups, and visible labels follow /language.响应式底栏优先显示当前权限姿态和交互状态；终端较宽时，模型、推理强度和工作模式在右侧成组显示，下方按可用性显示 Git、缓存、上下文、压缩余量、任务和余额。“就绪”表示输入框空闲；选择器、审批、图片粘贴、shell 模式等活动会替换它。窄终端会移动或压缩完整信息组，可见标签跟随 /language。

Mouse capture is on by default so Reasonix can handle transcript selection, wheel scroll, and the scrollbar. Turn it off with /mouse, or start with REASONIX_DISABLE_MOUSE=1, when you prefer the terminal's own selection behavior.默认会开启鼠标接管，用于对话选中、滚轮滚动和滚动条。需要终端自己的选中行为时，用 /mouse 关闭；也可以用 REASONIX_DISABLE_MOUSE=1 默认关闭。

In a local session, releasing an in-app text selection copies through the native system clipboard and shows success only after the write completes. SSH falls back to a clearly labelled OSC 52 request. Text paste remains your terminal's bracketed-paste shortcut, such as Cmd+V on macOS. Image paste is separate: use Ctrl+V on macOS/Linux, Alt+V on Windows, or /paste-image; the footer shows Pasting image… while the attachment is prepared.本地会话中，应用内文本选区会写入系统剪贴板，只有写入完成后才提示成功；SSH 会回退到明确标记的 OSC 52 请求。文本继续使用终端原生 bracketed-paste 快捷键，例如 macOS 的 Cmd+V。图片粘贴使用独立入口：macOS/Linux 按 Ctrl+V，Windows 按 Alt+V，或运行 /paste-image；附件准备期间底栏显示“正在粘贴图片…”。

/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 文件。

/goal is for long-running objectives. Ordinary chat never changes mode automatically. Normal goals stay lightweight; clearly long-horizon work can use the AutoResearch strategy, which keeps state under .reasonix/autoresearch/..., tracks evidence, and forces a new direction when progress stalls. Use /goal --research <objective> to force it or /goal --simple <objective> to keep the lightweight path. AutoResearch is a Goal strategy, not a separate app-start daemon or standalone built-in skill./goal 用于长目标。普通聊天不会自动切换模式。普通 goal 保持轻量；明显长周期的任务可以启用 AutoResearch 策略，在 .reasonix/autoresearch/... 下保存状态、记录证据，并在进展停滞时强制换方向。用 /goal --research <目标> 强制启用，或用 /goal --simple <目标> 保持轻量路径。AutoResearch 是 Goal 的策略，不是 App 启动即运行的 daemon，也不是独立内置 skill。

Use @path to inject files or directories, and @server:uri for MCP resources. Plan Mode is an explicit user choice: select it in the desktop collaboration control or cycle to it with Shift+Tab in the CLI. reasonix config reasoning-language auto|zh|en updates the user default from scripts; --local remains available for settings that support project-local overrides.用 @path 注入文件或目录,用 @server:uri 引入 MCP resource。计划模式始终由用户显式选择：桌面端在协作方式中选择，CLI 用 Shift+Tab 切换。脚本中可用 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, global provider-key file, 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、全局 provider 密钥文件、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。