1. 为什么要在本地跑一个 AI 编程代理Reasonix 是一个运行在本地开发环境里的 AI 编程代理它能直接进入你的项目目录读文件、搜代码、改内容、执行命令、跑测试然后根据测试结果继续排查。和常见的代码问答工具不同它不是给你一段代码让你自己复制粘贴而是在获得授权后真正参与到开发流程里。典型工作流是读取项目 → 分析问题 → 制定计划 → 修改代码 → 执行测试 → 检查错误 → 继续修复 → 输出验证结果。它最初围绕 DeepSeek 做了深度优化特别重视长会话的上下文稳定性和前缀缓存现在已经支持更广泛的模型后端包括 DeepSeek API、OpenAI-compatible、Anthropic-compatible、企业内部模型网关以及各种第三方聚合平台和自建代理。需要说明的是Reasonix 不是 DeepSeek 官方产品而是开源社区维护的第三方项目实际效果、接口兼容性和安全风险还是得自己评估。这篇教程面向从零落地的开发者覆盖安装、模型接入、权限配置到实战演练的完整流程。我会给出可复制的 config.toml 与 settings.json 骨架、TaoToken 统一 Key/API 通道接入步骤以及逐项验证动作连通性、权限生效、代理调用帮你一次跑通全流程。适合经常泡在终端的开发者、偏好图形界面的用户以及想把 Agent 接进 VS Code 等编辑器的人。2. 安装 Reasonix 与前置准备2.1 选择安装方式最通用的是 npm适合已经装了 Node.js 的环境npm install -g reasonix reasonix --versionmacOS 也可以用 Homebrewbrew install esengine/reasonix/reasonix桌面端提供 macOS .dmg、Windows .exe、Linux .deb 等安装包。如果 macOS 提示无法打开可以尝试sudo xattr -rd com.apple.quarantine /Applications/Reasonix.app需要二次开发的话也可以从源码构建需要 Go、Git、Make。Reasonix 1.x 用 Go 重写目标是降低运行时依赖打成单一原生二进制。整体架构可以理解成用户通过 CLI / TUI、桌面端、浏览器界面或 ACP 编辑器接入本地 ControllerController 负责 Agent 循环、文件与 Shell 工具、权限、沙箱、会话、记忆、检查点、Skills/Subagents 和 MCP 插件真正的模型推理则交给配置的 Provider。本质是“本地 Agent 云端模型”的混合架构代码和工具操作在本地完成需要推理的上下文再发给模型服务。2.2 准备统一 API 通道安装完后最关键的一步是配置模型。Reasonix 把模型设置分成两个区域使用区负责设置默认模型、Planner 模型、运行上限接入区负责管理供应商Provider。只有在接入里添加并启用的模型才会出现在会话选择器、/model 列表和 Planner 设置里。这里我建议用 TaoToken 作为统一 API 通道好处是一个 Key 可以对接多家模型省去在多个平台之间来回切换的麻烦。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。创建好之后把 Key 复制出来后面配置会用到。API 的基础地址是 https://taotoken.net/api 注意这个地址不带 UTM 参数配置时直接填这个就行。注意不要把完整密钥写进项目配置。供应商配置里只填环境变量名真实密钥放在全局 ~/.reasonix/.env 里。这样复制配置、上传仓库、分享截图时都更安全。3. 可复制的 config.toml 与 settings.json 骨架3.1 全局环境变量文件先在全局目录创建 .env 文件把真实密钥放进去mkdir -p ~/.reasonix cat ~/.reasonix/.env EOF TAOTOKEN_API_KEYsk-你的真实密钥 EOF chmod 600 ~/.reasonix/.env3.2 config.toml 骨架Reasonix 的供应商配置支持 TOML 格式。下面是一个可复制的骨架把 TaoToken 作为 OpenAI-compatible 供应商接入# ~/.reasonix/config.toml [providers.taotoken] name TaoToken protocol openai base_url https://taotoken.net/api/v1 api_key_env TAOTOKEN_API_KEY model_discovery true [models] default deepseek-chat planner deepseek-reasoner [limits] max_tokens 8192 max_turns 30几个关键点说明一下。base_url 通常带 /v1不要写完整的 chat/completions 路径。api_key_env 填的是环境变量名不是密钥本身。model_discovery 开启后可以自动刷新模型列表。模型名称必须和接口返回的 ID 完全一致大小写、连字符都不能错。3.3 settings.json 骨架如果你用的是桌面端或浏览器界面部分设置会落到 settings.json{ provider: taotoken, defaultModel: deepseek-chat, plannerModel: deepseek-reasoner, permissionMode: ask, sandbox: { workspaceOnly: true, denyPaths: [.ssh, .aws, .config/gcloud] }, enabledModels: [ deepseek-chat, deepseek-reasoner ] }聚合平台模型很多不建议一次全部启用。更实用的做法是只保留日常默认、高推理、快速低成本、Planner 专用和备用这几类。Planner 和执行模型可以分开强模型负责分析和规划轻量模型负责具体修改和测试对大型项目更划算。4. 权限配置与沙箱基线4.1 权限模式选择正式使用前建议先配好权限。基础示例[permissions] mode ask deny [Bash(rm -rf*), Bash(git push*), Bash(git reset --hard*)] allow [Bash(go test:*), Bash(npm test:*), Bash(git diff:*)]普通开发优先用 ask不要长期跳过审批。YOLO 模式虽然快但只有在项目已备份、目录无敏感数据、修改可回滚、且不涉及生产环境时才建议考虑。4.2 沙箱限制沙箱可以限制工作区读写禁止访问 .ssh、云凭据等敏感路径。上面 settings.json 里的 sandbox 段就是做这个的。不同系统沙箱能力有差异尤其 Windows 上要额外留意。4.3 浏览器界面的安全提醒不习惯终端可以用reasonix serve默认访问 http://127.0.0.1:8787 。如果需要监听其他地址必须开启鉴权token 或 password千万不要把没有鉴权的 Serve 直接暴露到公网——它有读文件、改代码、执行命令的权限风险比普通网页高得多。5. 验证请求与成功结果5.1 连通性验证配置完成后先跑一次能力检查reasonix doctor capabilities这个命令会检查 Provider 连通性、模型列表、权限配置和沙箱状态。如果模型列表能刷新出来说明 Base URL 和 Key 都没问题。5.2 权限生效验证启动一个 Plan 模式会话确认权限拦截生效reasonix --permission-mode plan在会话里输入一个会被 deny 的命令比如让它执行 git push观察是否被拦截。如果被正确拦截说明权限配置生效。5.3 代理调用验证进入一个测试项目目录给一个简单任务请阅读当前项目结构列出所有 Go 文件的函数名不要修改任何文件。如果它能正确读取文件并返回函数列表说明文件工具链正常。再让它跑一次 go test ./...确认命令执行和结果回传都正常。5.4 模型对话快速验证如果你想先单独验证模型通道是否通可以直接用模型对话页面测试https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。在这里发一条消息能正常返回就说明 Key 和通道没问题再去 Reasonix 里配置就更有底。6. 实战修复一个 Go 项目的 HTTP 重试机制假设项目结构是 demo-appHTTP 客户端缺少重试机制。进入目录后启动 Plan 模式cd demo-app reasonix --permission-mode plan给出明确要求请阅读当前项目结构定位 HTTP 客户端没有重试机制的问题。 要求先给出修改计划不要立即编辑代码只允许修改 internal/net 目录 不改公开函数签名不引入新依赖增加指数退避和最大重试次数 修改后运行 go test ./...最后输出修改摘要和测试结果。审核计划没问题后再批准文件修改和命令执行。完成后自己再跑一遍git diff go test ./...确认结果符合预期。AI 能提升效率但最终验证还是得掌握在自己手里。6.1 用子智能体做只读审查复杂任务可以拆给不同角色。比如创建一个只读审查子智能体reasonix subagent create reviewer \ --description Review changes for correctness and regressions \ --prompt-file reviewer.md \ --tools read_file,grep,bash \ --model deepseek-reasoner \ --effort high然后用 try 模式做只读检查不会修改文件比较适合代码审查和风险评估。6.2 会话记忆与检查点回退支持恢复上次会话、搜索历史、创建副本和分支、长期记忆、回退到修改前的检查点。常用命令有reasonix --continue reasonix --resume交互里也能用 /rewind、/branch、/switch、/memory。改坏了就回退这个在实战里非常实用。7. 本篇常见错误排查7.1 提示未设置 API Key检查变量名和 .env 是否一致。config.toml 里写的是 api_key_env TAOTOKEN_API_KEY那 .env 里就必须是 TAOTOKEN_API_KEYsk-xxx大小写要完全匹配。7.2 能刷新模型但发消息失败重点看协议类型、Base URL 路径、模型 ID、权限和余额。Base URL 应该是 https://taotoken.net/api/v1 不要多写或少写 /v1。模型 ID 要和接口返回的完全一致。7.3 模型存在但会话里看不到去“已启用模型”确认是否勾选。只有在接入里添加并启用的模型才会出现在会话选择器、/model 列表和 Planner 设置里。7.4 刷新列表失败检查 Base URL、/v1/models 支持情况、额外请求头和网络。如果用的是自建代理确认代理是否正确转发了请求头。7.5 权限拦截不生效确认 permissionMode 设置正确deny 列表里的模式匹配写法是否正确。Bash(rm -rf*) 这种写法匹配的是命令前缀注意通配符位置。7.6 沙箱阻止了正常操作如果发现正常读写被拦截检查 sandbox.workspaceOnly 是否设成了 true以及 denyPaths 里是否误加了项目目录。调整后重启会话生效。8. 长期编码与 Agent 场景的接入建议如果你打算把 Reasonix 用于长期编码或 Agent 场景建议关注 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它更适合需要持续调用、长会话稳定的开发场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的调用示例和参数说明。如果你用 Claude Code 或 Anthropic 兼容协议可以参考 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。一周入门路线可以这样安排第 1 天安装加模型配置熟悉 /help、/model第 2 天练习文件操作、改一处代码、看 Diff、跑测试第 3 天用 Plan 模式完成一个两到三步的真实任务第 4 天练习 /rewind、分支和记忆第 5 天接入一种扩展MCP / Subagent / Skill / ACP第 6 天建立权限和沙箱基线跑 reasonix doctor capabilities第 7 天选一个真实需求完整走一遍 Plan → 修改 → 测试 → 验证。个人开发者建议从 CLI Ask 权限 小型测试项目开始不要一上来就开放过多权限。团队则应该先把模型网关、凭据隔离、插件审核和代码审核流程建好再逐步引入。无论用哪个 AI 编程代理都建议坚持一个原则AI 可以帮你更快分析、修改和验证但涉及生产环境、数据安全和核心业务逻辑的变更最终仍需要人来审核和确认。
