Technical questions (advanced)
This page is for people using the CLI, bringing their own model endpoint, or building an integration. If you just want it to tidy up files, the regular FAQ is enough.
Installation and connection
How do I configure a model? After starting the CLI, enter /connect and follow the prompts to select a provider (DeepSeek / OpenAI / Custom), enter the API Key, select a model, and set the reasoning effort. No manual configuration file editing is required.
Where is the API Key stored? Could it be exposed in plaintext? It is stored locally in ~/.config/zqagent/, encrypted, and is never written to disk in plaintext.
Which models are supported? Any OpenAI-compatible endpoint works, such as DeepSeek, OpenAI, Ollama, or a self-hosted service. Use the "Custom" option in /connect, or set OPENAI_BASE_URL.
Getting the error Required parameter(s) missing or invalid / Responses API 调用失败? It is most likely that the selected model cannot be used for chat. The gateway's model list (/models) is often a "full catalog"; it also includes embedding (*-embedding), rerank (*-rerank), speech (*-asr / *-tts), realtime (*-realtime), image (qwen-image* / wan*), and dedicated-channel (cmaas-*) models, among others, which do not accept ordinary chat requests. /connect has already placed these models at the end of the list and marked them with ⚠️; after you select one, it also performs an automatic self-check once (actually sends a minimal request); if it does not work, it prompts you to choose again. Just switch to a chat model earlier in the list (such as qwen3.8-flash, qwen-plus, deepseek-flash).
Two types of reasons are given when the self-check fails:
| Prompt | Meaning | Action |
|---|---|---|
The product is not activated | The model is not activated under this API Key / account (or there are arrears / the quota is exhausted) | Activate the model in the gateway console, or switch to an activated model |
InvalidParameter: Required parameter(s) missing or invalid | The model name is not accepted by the chat interface, or unsupported parameters were passed for this service | Switch to a chat model; if it still fails, set reasoning effort to "Default" |
To manually verify whether a model works:
curl -s <BaseURL>/chat/completions \
-H "Authorization: Bearer $OPENAI_API_KEY" -H "content-type: application/json" \
-d '{"model":"<模型名>","messages":[{"role":"user","content":"hi"}]}'Installation error command not found, or downloads are very slow? The package is published on public npm; under normal circumstances, install it directly:
npm i -g @zqagent/coreSlow downloads are usually a network issue. You can temporarily switch to a domestic mirror (the mirror syncs automatically after release):
npm i -g @zqagent/core --registry=https://registry.npmmirror.com/For other installation issues, see Installation.
How do I choose between the stable and beta versions? Currently, public npm only publishes the stable version (@latest); there is no separate beta tag, so just install the latest version. See Installation.
Daily use
How do I switch run modes?/discuss (read-only conversation), /plan (read-only exploration + plan), /interactive (step-by-step approval, default), /auto (fully automatic, high risk). See CLI usage for details.
Are dangerous operations executed directly? In the default interactive mode, no: operations with side effects, such as writing files or executing commands, will first show an approval card, and you decide whether to allow or reject.
If a task runs for a long time, can I change the requirements midway? Yes. While the task is running, type text directly and press Enter; it will be injected as steering (supplemental input) in the next iteration. To start a separate task, interrupt first.
How do I interrupt a task that is stuck? Press ESC twice in a row.
Will a long conversation exceed the model's context window? No. When the threshold is reached, earlier conversation is automatically compacted, preserving key information, with no manual intervention needed.
How do I save and restore sessions?/sessions lists saved sessions and lets you choose one to restore; /clear clears the current session.
Nodes and console
How can I keep zqagent running continuously and also manage it remotely? Use zqagent serve to run persistently as a node, or install the desktop app. After connecting to the User Center, you can view it remotely. For steps, see Starting a node.
Can a browser manage nodes? What about a phone? Yes. After the node is connected, open the User Center in a browser to access the Node Console; mobile browsers are also supported (responsive layout + PWA, with "Add to Home Screen").
Where can I view usage and cost? In the usage panel of the Node Console (the token card on the project homepage, or "Monitoring → View usage" in node details), you can view statistics by time and model and export CSV; the account page also shows cross-node summaries.
Will unsent content be lost? No. Drafts in the console input box are automatically saved and automatically restored after switching sessions or refreshing the page.
If the network drops or I switch to the background during a session, will content be lost? No. The real-time event stream automatically reconnects after disconnection and fills in the deltas; after recovery, content is neither lost nor duplicated.
Desktop app
Do tasks keep running after I close the window? Yes. Closing the window only hides it to the tray; even if you "Quit" the app from the tray, the background node service is still kept alive by launchd / systemd.
Where is the data stored? Node data is in the system service data directory (macOS ~/Library/Application Support/zqagent/, Linux ~/.zqagent_data/, Windows %APPDATA%\zqagent\), shared with nodes installed by install.sh. Desktop preferences are stored separately in ~/.config/zqagent-desktop/desktop.json. See Desktop app → install details.
Remote control
Do I need a server with a public IP? No. Both mobile and QQ remote control use outbound connections and are completed through a third-party relay. See Remote control overview for details.
How do I use it from a phone / QQ? See Remote access and QQ bot.
Extending existing tools
How can I give the AI more tools? Connect to external tool servers via MCP, or use /tool add to add tools that execute commands. See MCP and tools for details.