跳到正文
Jz Desk

配置 Jz Desk

Jz Desk 本身不附带模型账号，用的是你的账号，并直接与 OpenAI 通信。最快的方式是用 ChatGPT 登录——三步完成，不需要密钥，也不用改任何文件。

  1. 第 1 步

    下载并安装

    在下载页获取适合你电脑的版本。所需的一切都在应用里，无需另外安装。

    macOS — 打开 .dmg，把 Jz Desk 拖进「应用程序」，再从「应用程序」中打开它。

    Windows — 运行安装程序。安装程序暂未签名，Windows 可能提示「Windows 已保护你的电脑」：点击「更多信息」，再点「仍要运行」。装好后从开始菜单打开 Jz Desk。

  2. 第 2 步

    用 ChatGPT 登录

    首次启动时，Jz Desk 会让你连接账户。点击「使用 ChatGPT 账户登录」：浏览器会打开 OpenAI 的登录页，在那里登录后，Jz Desk 会自动完成登录。用量计入你的 ChatGPT 套餐，无需创建 API 密钥。

  3. 第 3 步

    选个文件夹，提个问题

    选择一个让 Jz Desk 工作的文件夹，交给它一件事——问问里面有什么就行。收到回复，就说明配置好了。

改用 API 密钥

应用的登录界面只提供 ChatGPT 登录。想改用 OpenAI API 密钥，把它保存到一个文件里即可，之后 Jz Desk 会跳过登录界面。以下情况适合这样做：

  • 你通过中转或代理服务访问，它提供自己的密钥和地址，而不是直连 OpenAI；
  • 你的网络打不开 OpenAI 的登录页；
  • 比起 ChatGPT 套餐，你更想在 API 账户上按 token 付费。
  1. 第 1 步

    先打开一次 Jz Desk，然后退出

    按上面的方法安装并打开。出现登录界面时退出：macOS 按 ⌘Q；Windows 在任务栏通知区域右键 Jz Desk 图标，选择 Quit——直接关窗口只会把它藏起来。第一次启动会创建后续步骤要写入的配置文件夹。

  2. 第 2 步

    保存密钥

    把命令里的 sk-your-key 换成你自己的密钥后运行。它会整个替换登录文件，包括已有的 ChatGPT 登录——请用这条命令，不要手动把密钥加进文件，否则 Jz Desk 仍会沿用原来的 ChatGPT 登录。如果提示找不到文件夹，说明你的设置来自文件夹改名之前：把命令里的 .jz-desk 换成 .jz-code，下一步也一样。

    macOS — 在「终端」中运行：

    echo '{"auth_mode": "apikey", "OPENAI_API_KEY": "sk-your-key"}' > ~/.jz-desk/auth.json && chmod 600 ~/.jz-desk/auth.json

    Windows — 在 PowerShell 中运行：

    Set-Content -Encoding ascii "$HOME\.jz-desk\auth.json" '{"auth_mode": "apikey", "OPENAI_API_KEY": "sk-your-key"}'
  3. 第 3 步

    用中转或代理？把 Jz Desk 指向它

    如果你的密钥是直连 OpenAI 的，跳过这一步。否则打开配置文件：把开头的 model_provider 这一行改成下面第一段的样子，再把第二段加到文件最末尾，base_url 填中转服务的地址。如果文件里有 openai_base_url 这一行，删掉它。

    macOS — 用「文本编辑」打开：

    open -e ~/.jz-desk/config.toml

    Windows — 用记事本打开：

    notepad "$HOME\.jz-desk\config.toml" 
    model_provider = "relay"
    [model_providers.relay]
name = "Relay"
base_url = "https://your-relay.example.com/v1"
wire_api = "responses"
requires_openai_auth = true
  4. 第 4 步

    再次打开 Jz Desk

    它会读到密钥，直接进入。选个文件夹问个问题，确认能用。

中转地址通常以 /v1 结尾，且必须支持 OpenAI Responses API——只提供 chat completions 的中转用不了。请用上面这段配置，而不是 openai_base_url：用 openai_base_url 时，Jz Desk 会通过 WebSocket 连接中转，很多中转接受了连接却从不回应，于是每条消息都会一直等下去。

在 ChatGPT 和密钥之间切换

  • 从 ChatGPT 换成密钥：按上面第 2 到第 4 步操作即可，不用重装。
  • 从密钥换回 ChatGPT：退出 Jz Desk，删掉 auth.json；如果加过中转，把 model_provider 改回 "openai"。文件里如果有 model 这一行，也一并删掉——提供给 API 密钥的最新模型在 ChatGPT 登录下会被拒绝。再打开 Jz Desk，它会重新让你登录。
  • 卸载 Jz Desk 不会删除配置文件夹，重装后会沿用之前的登录和设置。

所有内容都在一个文件夹里：macOS 是 ~/.jz-desk，Windows 是 %USERPROFILE%\.jz-desk。auth.json 存登录信息，config.toml 存设置。在文件夹改名之前就装过 Jz Desk 的电脑会保留原来的 .jz-code，Jz Desk 也继续用它。

选择模型

在应用的模型选择器里选择模型；两种登录方式各有自己的默认模型。用 ChatGPT 登录时，你能用的是 OpenAI 在 Jz Desk 中为你的账号提供的模型，具体取决于你的 ChatGPT 套餐，可能只包含 GPT-6 系列中的一部分。用密钥时，你能用 GPT-6 系列，默认是 GPT-6.1-Sol；你的密钥或中转服务提供的其他模型也都能按名称使用。较小或较旧的模型在较长的多步骤任务上会比较吃力。

设置模型选择器里列出哪些模型

用 ChatGPT 登录时，选择器列出的是 OpenAI 为你的账号提供的模型；用密钥时，列出的是 Jz Desk 自带的 GPT 模型。想列出自己的——比如正好是中转服务提供的那些——把下面这样的模型列表存成一个 JSON 文件。它会替换整个列表，两种登录方式下都是，所以要把想用的模型都写进去：slug 是你的账号或中转服务提供的模型 id，visibility 设为 "list" 才会出现在选择器里，base_instructions 是模型工作时遵循的基本指令。

{
  "models": [
    {
      "slug": "gpt-6.1-sol",
      "display_name": "GPT-6.1-Sol",
      "description": "Through our relay",
      "base_instructions": "You are Jz Desk, an AI assistant working on the user's computer. Be precise and concise.",
      "visibility": "list",
      "priority": 1,
      "supported_in_api": true,
      "shell_type": "unified_exec",
      "default_reasoning_level": "medium",
      "supported_reasoning_levels": [
        { "effort": "low", "description": "Faster" },
        { "effort": "medium", "description": "Balanced" },
        { "effort": "high", "description": "Deeper" }
      ],
      "support_verbosity": true,
      "truncation_policy": { "mode": "tokens", "limit": 10000 },
      "context_window": 272000,
      "experimental_supported_tools": []
    }
  ]
}

然后在 config.toml 里把 model_catalog_json 指向这个文件的完整路径——必须是你电脑上的文件，不能是网址——再重新打开 Jz Desk。这一行要放在文件开头部分，任何 [段落] 之前。Windows 上请保留单引号，这样反斜杠会按原样读取：

model_catalog_json = "/Users/you/.jz-desk/models.json"
model_catalog_json = 'C:\Users\you\.jz-desk\models.json'

如果不工作

浏览器登录一直完成不了
在 Jz Desk 显示已登录之前，不要关闭浏览器标签页——最后一步要把登录结果交回你电脑上的应用。如果 OpenAI 的页面根本打不开，说明你的网络访问不到它，请改用 API 密钥并通过中转服务访问（见上文）。
一直等待，没有回复
用中转时，最常见的原因是设置了 openai_base_url：这时 Jz Desk 会尝试 WebSocket，很多中转接受了连接却从不回应。请改用第 3 步里的那段配置。否则就是地址不可达——检查地址，或检查网络能否访问 OpenAI。注意：旧版本留下的 config.toml 不会被覆盖，里面可能还留着旧设置。
模型不受支持
该模型不在你账号可用的范围内。用 ChatGPT 登录时，请从选择器里选一个模型，或删掉 config.toml 里的 model 这一行；用密钥时，请用你的密钥或中转服务提供的模型 id。改完后新建一个会话——已有会话会沿用创建时的模型。
401 或 403
用密钥时：密钥输错、已过期，或账户没有开通计费——用第 2 步的命令重新保存。如果密钥没错却仍提示无效，说明 auth.json 还处在 ChatGPT 模式，通常是手动把密钥加进文件造成的；运行第 2 步的命令即可。用 ChatGPT 时：登录已失效，删掉 auth.json 再打开 Jz Desk 重新登录。
Windows 上保存密钥的命令出错
请在 PowerShell 而不是命令提示符中运行，并且要在打开过一次 Jz Desk 之后——在那之前，它要写入的文件夹还不存在。