XunOPC 使用文档

安装与首次启动

从官方下载页选择与你的 Mac 匹配的安装包：芯片显示 Apple M1 / M2 / M3 / M4 等，下载 arm64；显示 Intel，下载 x64。

1. 双击 DMG，把 XunOPC 拖进「应用程序」，随后从 Launchpad 或「应用程序」目录启动。
2. 从「应用程序」打开。正式安装包已经润迅 Developer ID 签名并通过 Apple 公证，不需要运行 xattr 等额外命令。
3. 首次启动后先进入「设置 → MaxModel」完成模型配置，再创建项目和会话。

配置 MaxModel：一个密钥，接入所有大模型

打开「设置 → MaxModel → 配置 MaxModel」，粘贴从 MaxModel 获取的 API Key。接口地址保持 https://api.maxmodel.com，不要手动追加 /v1。

• 选择模型：页面会同步 MaxModel 在线模型目录，可按名称、模型 ID 或厂商搜索。目录暂时不可用时，仍可手动输入模型 ID。
• 四类映射：主模型、快速模型、均衡模型和高性能模型可分别选择；只想使用一个模型时可以设为相同 ID。
• 高级上下文：已知模型会自动采用对应上下文窗口。只有网关限制发生变化或使用自定义模型 ID 时，才需要手动调整。
• 保存前测试：点击「测试连接」，确认连接性与模型代理转换两步都通过。

完成第一项任务

1. 点击左侧「新建会话」，选择「使用现有文件夹」或创建空白项目。
2. 确认工作目录、模型与权限模式。首次使用建议保留「询问权限」。
3. 把目标、范围和验收标准一次写清；需要时直接粘贴图片、拖入文件，或使用 @ 引用工作区文件。
4. 执行过程中审阅工具调用和权限申请；完成后在工作台查看更改文件、Diff、输出物和运行结果。

经营台与决策收件箱

经营台不是装饰性仪表盘。它读取本机真实的会话、权限请求、定时任务和运行结果，集中回答三件事：系统正在做什么、已经交付什么、现在需要你决定什么。

• 需要你决定：等待处理的工具权限与电脑操作申请。点击「去处理」会回到来源会话，保留完整上下文。
• 已替你完成：最近自动任务留下的真实完成记录。
• 自动工作时间：根据已完成任务的实际运行时长统计，不用虚构的“节省成本”替代事实。
• 需要介入：最近检测到的失败和超时，可直接转到定时任务继续处理。

项目、会话与独立 worktree

项目以真实本机目录为边界，侧栏按项目归档会话。可以搜索全部聊天内容、置顶或隐藏项目、在访达中打开目录，并在指定项目中继续新建会话。

• 当前目录：适合直接在现有工作区继续做事。
• 独立 worktree：为并行任务创建隔离工作目录，不触碰你正在使用的分支和未提交改动。
• 脏工作树保护：项目存在未提交改动，或目标分支已被其他 worktree 使用时，直接切换会被阻止；选择独立 worktree，或先自行提交 / 暂存。
• 历史仍保留：临时 worktree 清理后，会话记录仍可查看；继续工作时在原项目中创建新会话。

工作台、审阅与交付物

右侧工作台把对话与真实产物放在一起，减少在 Finder、编辑器和浏览器之间来回切换。

• 文件与 Diff：浏览所有文件或只看已更改文件，按行查看新增、删除、重命名和未跟踪内容。
• 把意见送回会话：选中 Diff 行添加评论，再把评论加入对话，让 XunOPC 按具体位置继续修改。
• 预览与浏览器：直接预览代码、文档、图片和本地网页；对 localhost 输出可在应用内继续验证。
• 输出物：助手生成的 Markdown、HTML、图片、本地服务等会作为可打开结果显示，不必从长对话里重新寻找。
• 终端与历史：需要时打开宿主机终端；会话历史和运行状态独立保留。

6 个内置智能体

在「设置 → 智能体」查看当前生效的内置、用户、项目、本地、插件和托管来源。每个智能体都有职责、模型、工具范围和系统提示词；同名定义可能被更高优先级来源覆盖。

• 通用智能体：研究复杂问题、搜索代码并执行多步骤任务。
• 代码探索：按路径、文件模式或关键词快速理解代码库。
• 方案规划：拆解实现步骤，指出关键文件、依赖关系和架构取舍。
• 质量验证：交付前运行构建、测试和检查，给出明确结论。
• XunOPC 指南：回答产品设置、命令、MCP、技能与开发接口问题。
• 状态栏设置：配置 XunOPC 状态栏显示内容。

权限模式与可信执行

• 询问权限：执行工具前先询问，推荐作为默认模式。
• 接受编辑：自动批准文件编辑，命令、外部操作等仍需询问。
• 计划模式：只分析和规划，不执行修改。
• 跳过全部：跳过权限检查，风险最高，只适合边界清晰且可恢复的受控环境。

权限卡会展示工具类型、命令或改动预览。可以仅允许本次、在当前会话内持续允许同类操作，或拒绝。所有待处理申请也会进入经营台的决策收件箱。

技能、插件与项目记忆

• 技能：把稳定做法封装成可复用工作说明。技能中心可搜索内置、用户、项目、插件和 MCP 来源，并查看入口文档与配套源码。
• 插件：把技能、智能体、命令、 Hooks、MCP 和语言服务打包管理。启用、禁用或更新后，点击「应用变更」让当前桌面运行时重新加载。
• 项目记忆：按项目查看和编辑 Markdown 记忆文件。它们保存在本机项目记忆目录中，并由 XunOPC CLI 在后续运行时加载。

插件或技能来自外部时，先检查作者、安装位置、入口文件和将要暴露的能力。停用不再需要的扩展，避免工具集合无限膨胀。

MCP 服务：接入外部工具与数据源

打开「设置 → MCP → 添加服务」，可以连接 STDIO、Streamable HTTP 或 SSE 服务。页面会显示服务总数、连接状态和需要处理的异常。

• 项目私有（Local）：只对当前用户生效，同时绑定一个项目。
• 项目共享（Project）：写入项目的 .mcp.json，可随项目与团队共享。
• 全局用户（User）：写入用户级 XunOPC 配置，对所有项目生效。

STDIO 服务直接在宿主机运行，所需的 Node.js、Python、Bun、uv 等运行时必须已经安装并能从 PATH 找到。HTTP / SSE 可设置 URL、请求头和 OAuth 参数；API Key、Token、Secret、Password 等字段在展示时会脱敏。

定时任务：让重复工作按计划运行

从侧栏进入「定时任务」，或在现有会话中使用创建定时任务的命令。任务可设置名称、目标提示、工作目录、执行频率、模型、权限和完成通知。

• 支持每 N 分钟 / 小时、每天、工作日、指定星期、每月和自定义 Cron。
• 可随时启用、暂停、手动运行，查看上次结果、下次执行和输出物。
• 完成后可以发送桌面通知，或推送到已经配置的 IM 渠道。
• 失败和超时会进入经营台的“需要介入”，方便集中处理。

消息接入与账号配对

「设置 → 消息接入」支持 Telegram、飞书、微信、钉钉和 WhatsApp。可以设置平台凭证、默认项目、允许用户，并让定时任务完成后把结果推送到消息渠道。

• 机器人凭证：Telegram 使用 Bot Token；飞书使用 App ID / App Secret；钉钉可扫码创建并授权机器人。
• 账号扫码：微信和 WhatsApp 的二维码用于把一个可收发消息的账号能力绑定给本机适配器。扫码确认后，适配器会自动重启建立连接。
• 用户配对码：二维码绑定不等于允许所有联系人使用 XunOPC。具体用户仍需在私聊中发送桌面端生成的配对码，或被加入“允许的用户”。
• 默认项目：新 IM 会话默认在哪个目录工作由这里决定；留空时使用当前用户工作目录。

电脑操作：让 Agent 看见并操作桌面

电脑操作允许 XunOPC 截屏、识别界面、点击和输入。macOS 与 Windows 支持该能力；macOS 还需要系统辅助功能和屏幕录制权限。

1. 进入「设置 → 电脑操作」，确认系统能找到 Python 3；使用 conda、pyenv 等环境时可手动选择解释器。
2. 点击「环境安装」，创建隔离虚拟环境并安装屏幕识别、鼠标键盘控制和系统集成组件。
3. 在 macOS「系统设置 → 隐私与安全性」中允许辅助功能与屏幕录制，随后重启 XunOPC。
4. 启用电脑操作，并选择可预先批准的应用。未预先批准或被视为敏感的应用仍会在会话中请求确认。

手机远程访问

「设置 → 远程访问」可以让同一可信局域网内的手机打开 XunOPC H5 界面。启用后生成访问令牌和二维码，手机扫码即可连接桌面会话。

• 普通局域网访问填写本机可达的局域网 IP；需要反向代理时可配置完整公开 URL、固定端口和允许来源。
• 手机锁屏或切后台短暂断连时，运行中的任务会继续；“断连保活”决定空闲且无人连接后多久停止 CLI。
• 二维码中包含访问令牌，拿到链接的人可以访问 H5 暴露的桌面能力，应像密码一样保护。

数据、自动更新与迁移

• 本机数据：会话、设置、技能、MCP、插件、项目记忆、任务和缓存默认保存在本机。高级用户可在通用设置中切换自定义数据目录。
• 自动更新：正式版从润迅官方国内更新源检查新版本，Apple 芯片和 Intel 使用独立通道。下载完成后按提示安装并重启。
• 更新前：保存正在编辑的内容，等待重要会话或电脑操作结束；安装重启不会主动删除已有会话和配置。
• 诊断与调用记录：设置中的“诊断”和“调用记录”用于定位配置、数据或模型调用问题；分享日志前先检查并移除敏感内容。

故障排查

• 新建会话提示断开、重试或 ECONNRESET：先在「设置 → MaxModel」测试连接，确认 API Key、当前模型和网络可用；再重启会话。持续出现时到「设置 → 诊断」查看本地错误。
• 模型目录加载失败：点击刷新；目录不可用不影响手动填写模型 ID。确认接口地址没有误加 /v1。
• 网关返回 400 参数不支持或输出上限过大：先更新到最新版并重新选择该模型，让目录预设重新应用；仍失败时降低输出 / 推理强度，或在 MaxModel 高级设置中关闭实验性 Beta 头。
• 电脑操作显示组件未安装：确认 Python 3 可用，点击「环境安装」，再检查 macOS 辅助功能和屏幕录制权限；授权后重启应用。
• 定时任务没有执行：确认任务已启用、电脑未休眠且 XunOPC 一直打开；本地任务不会在应用关闭时运行。
• 微信 / WhatsApp 已扫码但不能对话：扫码只完成账号绑定；还需让该用户发送配对码，或把用户 ID 加入允许列表。
• 更新已下载但重启异常：先退出正在运行的会话和终端，再完全退出 XunOPC 后重新打开；仍失败可从官方下载页覆盖安装同一架构版本。

联系与反馈

产品使用、企业部署、消息渠道接入与问题反馈，请联系润迅。反馈故障时请提供 XunOPC 版本、Mac 架构、复现步骤和已经脱敏的错误信息；不要发送 API Key、访问令牌或客户数据。