技术问题（高级）
这一页面向用命令行、接自建模型或做集成的用户。 如果你只是想让它帮忙处理文件，看常见问题就够了。
安装与连接
怎么配置模型？ 启动 CLI 后输入 /connect，按提示选择 provider（DeepSeek / OpenAI / 自定义）、填 API Key、 选模型、设置推理强度即可。无需手写配置文件。
API Key 存在哪里？会不会明文泄露？ 保存在本机 ~/.config/zqagent/，加密存储，不会明文落盘。
支持哪些模型？ 任何 OpenAI 兼容端点都可以，例如 DeepSeek、OpenAI、Ollama 或自建服务。用 /connect 的"自定义"选项，或设置 OPENAI_BASE_URL。
报错 Required parameter(s) missing or invalid / Responses API 调用失败？ 多半是选到的模型不能用于对话。网关的模型列表（/models）往往是"全量目录"， 里面还包含向量（*-embedding）、重排（*-rerank）、语音（*-asr / *-tts）、 实时（*-realtime）、图像（qwen-image* / wan*）以及专用通道（cmaas-*）等 模型，它们不接受普通的对话请求。/connect 已把这些模型排到列表末尾并打上 ⚠️ 标记，选定后还会自动自检一次（真发一条最小请求），不通就会提示你重选。 换到列表前面的对话模型（如 qwen3.8-flash、qwen-plus、deepseek-flash）即可。
自检失败时给出的两类原因：
| 提示 | 含义 | 处理 |
|---|---|---|
The product is not activated | 该模型在此 API Key / 账号下未开通（或欠费、额度用尽） | 到网关控制台开通该模型，或换已开通的模型 |
InvalidParameter: Required parameter(s) missing or invalid | 模型名不被对话接口接受，或多传了该服务不支持的参数 | 换对话模型；仍不行就把推理强度设为「默认」 |
手动验证某个模型能不能用：
curl -s <BaseURL>/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" -H "content-type: application/json" \
-d '{"model":"<模型名>","messages":[{"role":"user","content":"hi"}]}'安装报错 command not found 或下载很慢？ 包发布在公共 npm，正常情况下直接安装即可：
npm i -g @zqagent/core下载慢通常是网络问题，可临时换用国内镜像（镜像会在发布后自动同步）：
npm i -g @zqagent/core --registry=https://registry.npmmirror.com/其它安装问题见安装。
稳定版和测试版怎么选？ 目前公共 npm 只发布稳定版（@latest），没有单独的测试版标签，直接装最新版即可。 见安装。
日常使用
怎么切换运行模式？/discuss（只读对话）、/plan（只读探索 + 计划）、/interactive（逐次审批，默认）、 /auto（全自动，高风险）。详见 CLI 使用。
危险操作会被直接执行吗？ 默认交互模式下不会：写文件、执行命令等有副作用的操作会先弹出审批卡片，由你决定放行还是拒绝。
任务跑很久，能中途改需求吗？ 可以。任务运行中直接输入文字并回车，会作为补充信息在下一个迭代注入。要另起任务请先中断。
任务卡住了怎么中断？ 连按两次 ESC。
长对话会超出模型的上下文窗口吗？ 不会。达到阈值时会自动压缩较早的对话，保留关键信息，你无需手动干预。
怎么保存和恢复会话？/sessions 列出已保存会话并选择恢复；/clear 清空当前会话。
节点与控制台
怎么让 zqagent 一直运行、还能远程管理？ 用 zqagent serve 常驻为节点，或安装桌面应用。接入用户中心 后即可远程查看。步骤见启动节点。
浏览器能管理节点吗？手机呢？ 可以。节点接入后，浏览器打开用户中心即可进入节点控制台；手机浏览器同样支持 （响应式布局 + PWA，可「添加到主屏幕」）。
在哪里看用量和成本？ 在节点控制台的用量面板（项目首页 token 卡，或节点详情「监控 → 查看用量」）， 支持按时间与模型统计、导出 CSV；账号页还能查看跨节点汇总。
未发送的内容会丢吗？ 不会。控制台的输入框草稿会自动保存，切换会话或刷新页面后自动回填。
会话中途断网或切到后台，内容会丢吗？ 不会。实时事件流会断线自动重连并补齐增量，恢复后内容不丢失、不重复。
桌面应用
关闭窗口后任务还在跑吗？ 在跑。窗口关闭只是隐藏到托盘；即使从托盘「退出」应用，后台的节点服务仍由 launchd / systemd 保活。
数据存在哪？ 节点数据在系统服务的数据目录（macOS ~/Library/Application Support/zqagent/、 Linux ~/.zqagent_data/、Windows %APPDATA%\zqagent\），与 install.sh 安装的节点共用。 桌面偏好另存在 ~/.config/zqagent-desktop/desktop.json。详见 桌面应用 → 安装细节。
远程控制
需要一台有公网 IP 的服务器吗？ 不需要。手机与 QQ 远程都走出站连接，通过第三方中转完成。详见远程控制概览。
怎么从手机 / QQ 使用？ 见 远程接入 与 QQ 机器人。
扩展现有工具
怎么让 AI 拥有更多工具？ 通过 MCP 接入外部工具服务器，或用 /tool add 添加执行命令的工具。详见 MCP 与工具。