title: 认识 XChat一个把 LLM Agent 装进本地的跨平台客户端date: 2026-10-12tags: [XChat, Flutter, LLM, Agent, ReAct, 开源]summary: XChat 是一款基于 Flutter 的跨平台 LLM Agent 客户端用 ReAct 循环让模型自己调用工具完成任务会话以 XML 存在你自己磁盘上。这篇博客带你从定位、亮点到上手与数据管理快速认识它。认识 XChat一个把 LLM Agent 装进本地的跨平台客户端如果你用过网页版聊天机器人大概会有两个遗憾它不会替你动手只能聊不能读文件、跑命令、搜网页数据也不在你手里会话、Key、上下文都在别人服务器上。XChat 想解决的就是这两件事。它是一款基于Flutter的跨平台LLM Agent 客户端——接入任意 OpenAI 兼容以及 Anthropic / Gemini模型服务用ReAct 循环让模型自己调用工具把任务做完而所有会话、配置、脚本都以本地文件形式保存在你自己的磁盘上。本文基于 XChatv0.3.6的界面整理项目仓库当前已发布 v0.3.7截图取自 Linux 版本运行界面。界面文案与菜单位置在不同版本间可能微调请以实际版本为准。一、XChat 是什么维度内容形态原生 GUI不是WebView 套壳的 LLM Agent 客户端Flutter 实现平台Android / iOS / macOS / Windows / Linux协议OpenAI 兼容 API 为主另含 Anthropic / Gemini 适配层AgentReAct 循环模型 → 工具 → 模型…带工具次数预算与自动续判持久化全部本地文件会话为 XMLCDATA、配置为 JSON根目录Documents/XChat/许可MIT 开源一句话它是你自己的「模型外壳」——模型服务由你选数据由你保管而它负责把模型和你的文件、命令、网络连接起来。二、它最值得关注的几个差异点不是又一个「聊天框」XChat 的功夫主要在 Agent 工程细节上亮点说明Agent 自动调用工具模型输出 → 需要工具就调用 → 工具结果回灌 → 继续直到给出答案工具次数预算 自动续判达到上限后自动追加一条「续判」消息由模型自己判断继续还是收尾避免死循环思考链双模式同时支持reasoning_contentdeepseek / kimi / glm / mimo与thinkminimax两种思考形态显示并且回发Token 用量统计单次 in / out / cache 与累计用量、当前上下文长度都写进会话文件沙箱文件工具读写文件被限制在会话工作目录内越界路径..、符号链接会被拦截三级工具审批每个工具可设审批等级配合「普通 / 自动 / 托管」执行模式控制打断频率隐藏 WebView 联网搜索在离屏浏览器环境里搜索多引擎回退、多页聚合绕开直连反爬多会话并行切换会话不中断后台生成还配了一个跨会话的全局审批中心本地 XML 存储会话就是可读的 XML 文件整库复制即备份可迁移可手改三、五分钟上手1. 安装按平台取对应产物解压或安装即可首次启动无需任何初始化配置应用会自动创建数据目录并写入初始config.json。平台安装产物Windowsxchat-windows-x64-vX.Y.Z.zip解压得xchat.exeLinux.deb安装包Android.apkmacOS / iOS使用对应平台的构建产物Linux 用户注意若联网搜索报错多为缺少 WebKitGTK 4.1 运行时deb 包已声明依赖libwebkit2gtk-4.1-0。Android 用户可选想把数据放到共享目录Android 11 需授予「所有文件访问」权限未授权会自动回退到应用私有目录。2. 配置模型服务第一个必须完成的步骤入口首页 ☁ 模型服务。点右下角「 添加」向导会带你搜索提供商、勾选模型默认已预选最新 10 个支持工具调用的模型最后填API Key并点 测试连接。这里有两个概念值得分清当前生效服务左侧单选圆点选中的那一项作为新会话的默认提供商。应用功能调用模型专供应用自身功能会话 AI 自动命名、模板提示词生成等使用可以和主对话用不同的模型。还可以用models.dev一键同步模型目录上下文窗口、输出上限、能力标记它会按「服务 ID → 端点 host → 预设别名」匹配条目。同步有一条安全边界不会覆盖你填的自定义镜像地址、API Key、Headers 与思考回发设置。XChat 本身不提供模型——第 2 步配置完成前新建会话可以完成但发不出消息。3. 新建会话入口首页 侧边栏 或某个项目行尾的「」表示在该项目内新建。一页式表单最上方一排「起点」胶囊是精华空白 从零开始其余胶囊如 Coder、Flutter Coder、web-search、企业 AI/Agent 设计… 套用已保存的会话模板模型、参数、工具、预算、系统提示词全部自动预填。标题可以留空第一轮对话结束后会由模型自动命名≤20 字中文标题。系统提示词的**首行会作为「工作空间根目录」**写入对话告诉模型它的沙箱绝对路径在哪里。4. 开始对话聊天面板顶部一行信息量很大会话名 模型选择器以及in / out / cache / ctx用量与上下文进度条还有工具 0/20这样的工具调用计数。底部输入区里执行模式胶囊普通 / 自动 / 托管与「联网」开关决定了本轮 Agent 的行为。想让它真正「干活」就选一个支持 function calling 的模型然后把任务交给它——文件、命令、搜索它会自己决定调什么工具。四、界面导览窗口较宽≥ 820 逻辑像素时是「左右分栏」左边会话项目列表右边聊天区窗口变窄则自动切换为「列表 ↔ 聊天」两页路由移动端体验一致。顶部工具栏只有四个图标 工具审批、▦ 模板、☁ 模型服务、⋮ 更多。低频入口统一收在「更多」里即手动搜索 / 工具管理 / 归档管理 / 设置。找不到某个功能时先看「更多」。五、Agent 是怎么「自己干活」的XChat 的 Agent 采用经典的ReAct 循环模型输出 → 需要工具就调用工具 → 工具结果回灌 → 模型继续 → … → 给出答案其中两个机制值得单独说① 工具次数预算 自动续判。会话有一个工具调用上限但这个上限作用于每个续判周期。当累计调用达到上限时应用会自动追加一条用户侧消息让模型自己判断已完成 → 直接输出最终答复不再调用工具仍需继续 → 自行发起新一轮工具调用预算重置。「上限后的处理」可三选一模型自判默认/ 询问用户 / 直接结束在设置 默认参数中配置。续判提示词支持{n}累计次数与{limit}本轮上限占位符可自定义。② 执行模式与审批。会话有普通 / 自动 / 托管三档执行模式值 1/2/3每个工具有审批等级 0–3。规则是当模式值 ≤ 审批等级时弹出审批。等级含义典型工具0从不审批read_file、list_dir、glob、http_fetch、web_search1仅普通模式审批write_file、edit_file2普通 / 自动模式都审批—3总是审批shell、WebView 脚本挂载 / 卸载所以在「托管」模式下绝大多数工具都不会再打断你。六、工具与安全边界入口首页 ⋮ 更多 工具管理。每个工具一行右侧是审批等级下拉框。内置工具覆盖了本地文件、命令执行与网络工具作用read_file/write_file/edit_file读文件图片会作为图像返回给模型/ 覆盖写 / 精确字符串替换list_dir/glob列出目录 / 按通配符匹配路径shell执行命令桌面端工作目录 沙箱默认关闭需显式开启attach_image把沙箱内图片附加到对话下一轮可见http_fetchGET 抓取 URL 并转为纯文本可走代理web_search隐藏 WebView 联网搜索多引擎回退、多页聚合webview_fetch/webview_extract渲染页面取内容 / 按解析脚本提取结构化结果webview_script_mount等挂载、列出、卸载页面解析脚本持久化datetime返回本地与 UTC 当前时间安全边界有三层沙箱文件类工具只能访问会话工作目录及其子目录应用做真实路径前缀校验拦截..与符号链接逃逸。Shell 命令分级shell 命令按三条正则名单分级——**F 级deny**永不执行如sudo、mkfs、shutdown、rm -rf /、2 级高危副作用命令rm/mv/chmod…、1 级日常命令git/npm/pip/docker…优先级F 2 1 基础等级。⚠️任意一条名单为空shell 工具会被整体禁用——遇到 shell 不可用时先点一下「应用默认名单」。全局审批中心多会话并行时审批请求不会因为切换会话而丢失顶部工具栏最左侧的 图标是跨会话队列可集中允许或拒绝。七、联网搜索入口首页 ⋮ 更多 手动搜索。这个页面是搜索链路的「可视化验证台」与 Agent 调用的web_search共用同一套实现。为什么搜索要跑在「隐藏 WebView」里而不是直接发 HTTP 请求因为直连搜索引擎容易被反爬拦截TLS 指纹等特征。XChat 的做法是在真实浏览器环境离屏 WebView 会话中执行搜索多引擎回退引擎按配置列表顺序依次尝试某个失败自动换下一个多页聚合按「下一页」选择器逐页翻跨页去重合并某页没有新增结果就提前结束脚本提取可以为特定站点挂载解析脚本用webview_extract拿到结构化结果脚本一次挂载、持久复用。翻页诊断会写入logs/webview/paging.log提取为空时的页面 HTML 会落盘到logs/webview/last.html便于排查。八、会话管理会话「更多」菜单会话行 ⋮提供了从查看到删除的 11 项操作几个实用能力克隆三档克隆到首轮之前 / 含首次对话 / 完整会话。新会话获得新的 id 与时间戳工具计数与累计用量清零但提供商、模型、参数、工具、系统提示词全部保留。编辑重发修改最后一次 user 消息即重发——系统会删除其后所有内容替换为你的新文本并重算计数与用量。会话压缩上下文变长后把历史转写成一份 Markdown 摘要形成「摘要 handoff 后续对话」的新形态摘要即代表此前全部上下文。项目分组项目 会话分组 共享工作目录 默认提供商 / 模型适合把「同一件事」的多轮尝试归到一起。归档会话与项目都支持归档可恢复删除前先存档更稳妥。会话模板首页 ▦ 模板把「模型 参数 工具 预算 系统提示词」打包成可复用配置新建会话一键就绪模板向导里还有个好用的功能——用 LLM 生成系统提示词选一个场景类别商业 / 办公 / 生活 / 编程 / 旅游并描述用途模型会流式产出 system prompt不满意还能继续下指令迭代改写。另外会话控制器按 id 全局持有切换会话不会中断后台流式对话边栏对应会话会显示旋转指示。九、数据与隐私这是 XChat 最让人安心的一点数据全在本地格式开放可读。数据根/ # 桌面端 ~/Documents/XChat ├─ config.json # 全局配置提供商、默认参数、工具、代理… ├─ index.json # 会话 / 项目目录索引 ├─ models_dev.json # models.dev 目录缓存 ├─ sessions/ # 默认沙箱uuid.xml ├─ projects/id.xml # 项目定义 ├─ projects/id/ # 项目工作目录 ├─ templates/ # 会话模板 id.xml ├─ scripts/ # 页面解析脚本 id.json ├─ sandboxs/ # 各会话独立工作目录 └─ logs/ # 诊断日志logs/webview/ 为搜索落盘整库备份直接复制整个数据根目录即可会话、模板、配置、脚本全在其中。写出是原子的所有持久化都采用「先写临时文件、再重命名」的方式异常中断不会写出半截文件。会话自包含用户选图与 Agent 附加图片都会被复制到sandbox/attachments/而不是引用原路径因此单独拷走一个会话目录也能完整还原。⚠️API Key 就保存在本地config.json中分享数据目录前请先检查不要连同 Key 一起发出去。十、设置一览入口首页 ⋮ 更多 设置。上半部分包含数据目录展示 / 打开 config.json / 应用新目录并迁移 / Android 申请外部存储权限、压缩会话维护预置压缩提示词、默认参数默认工具调用上限、单张图片体积上限、默认思考开关、达到工具上限后的处理与续判提示词、搜索引擎管理。下半部分是搜索引擎与代理引擎列表顺序即回退顺序可上移 / 下移 / 启停 / 编辑URL 模板用{query}作关键词占位符代理http_proxy/https_proxy/no_proxy可设置为仅对http_fetch生效避免影响其他网络请求。设置页还包含外部编辑器命令{file}占位如code --goto {file}、主题跟随系统 / 亮 / 暗、桌面窗口尺寸预设等。十一、平台支持与获取平台数据位置备注Linux / macOS~/Documents/XChat/Linux 搜索依赖 WebKitGTK 4.1Windows文档\XChat\搜索依赖 WebView2Win10/11 通常自带Android{外部存储}/com.yimo.xchat/data已授权或应用私有目录可申请「所有文件访问」迁移数据项目仓库获取安装包与源码GitHubhttps://github.com/paiooocn/xchatGitCode 镜像https://gitcode.com/yimopub/xchat具体下载地址、版本号与产物命名请以仓库最新 Release 为准。十二、它适合谁想把 AI 接进自己工作流的人让 Agent 读写项目文件、跑命令、查资料而不是复制粘贴。关心数据归属的人会话、Key、上下文都在本机格式开放随时可迁移可备份。需要多任务并行的人多会话同时跑、跨会话审批队列、项目分组适合把不同事情摊开。爱折腾模型的人任意 OpenAI 兼容端点 本地 Ollama / llama.cpp思考链双模式、Token 统计一应俱全。结语XChat 的定位很清晰做一个真正能干活的本地 Agent 外壳。它把 Agent 工程里那些容易被忽略的细节工具预算、思考回发、沙箱边界、审批队列、翻页验证都认真做了处理同时把数据的所有权完整地交回给你。如果你也想让模型替你「动手」而不是只陪你「聊天」不妨试试它。附延伸阅读完整操作步骤含逐屏截图与 FAQ仓库根目录的XChat-使用教程.html功能点全清单适合重写/移植参考FEATURES.md设计动机与决策DESIGN.md本文所有截图均取自 XChat v0.3.6 的 Linux 构建版本若你的版本界面与此不同请以实际版本为准。
