配置 Provider 与模型
AI Provider 配置属于当前桌面设备，不属于单个 App，也不会随源工程或 Git 一起迁移。开始前先确定模型由谁提供、费用由谁承担，以及当前设备能否访问对应服务。
先选择模型来源
| 来源 | 适合谁 | 在哪里配置 | 请求与费用 |
|---|---|---|---|
| Qixin AI | 使用个人钱包或组织钱包的平台用户 | 系统设置 → AI 设置 → Qixin AI | 使用当前选择的钱包和平台模型 |
| 组织模型 | 所在组织已下发私有模型的成员 | 组织管理员在 Portal 配置；成员在 AI 设置中选择该组织 | 成员设备直连组织服务，不扣 Qixin 钱包 |
| 个人 BYOK | 当前 Qixin 账号已获得 BYOK 权限的用户 | 系统设置 → AI 设置 → 个人 AI 服务 | 使用自己的订阅、API Key 或 OAuth 登录 |
个人 BYOK 权限只控制“个人 AI 服务”区域，不影响 Qixin AI 或组织模型。该区域不可见时，先确认登录了正确的 Qixin 账号及其 BYOK 权限，不要通过修改本地文件绕过界面。
配置 Qixin AI
- 打开系统设置 → AI 设置，使用 Qixin 账号登录。
- 在 Qixin AI 卡片中选择个人钱包或组织钱包。
- 选择使用此账户。已经选中该账户时，可选择重新连接以重新取得当前账号和组织配置。
- 检查 Qixin AI 模型。列表未加载或平台刚调整模型时，选择刷新模型。
- 打开 AI Command Center，在模型选择器中明确选择需要的 Qixin AI 模型。
Theseus 会恢复这台设备上仍有效的账户选择；没有已有选择时优先选择可用的组织账户，否则选择个人钱包。切换账户不会新建或清空会话，之后发送的 Qixin AI 请求使用发送时选中的账户。发送前可从 AI Command Center 顶部的账户图标再次核对。
Qixin AI 使用所选钱包。余额、消费记录和账户管理在 Qixin Portal 中完成；AI 设置只负责选择账户、连接凭据和加载模型。某个模型下线后，已有会话不会静默切换到其他模型，而会要求重新选择。
使用组织模型
组织模型由组织统一管理，成员不能在本机修改其 Endpoint、认证方式或模型清单。
组织管理员
- 打开 Qixin Portal → 组织 → 对应组织 → AI 提供商。
- 添加 OpenAI-compatible Base URL，选择无认证或组织共享密钥，并填写允许成员使用的明确模型清单。
- 保存并通知成员在桌面端重新连接该组织。
组织成员
- 在系统设置 → AI 设置中选择配置了私有模型的组织账户。
- 选择使用此账户；配置发生变化后选择重新连接。
- 确认 组织模型区域出现所需模型。
- 在 AI Command Center 中选择该模型并先发送一个只读测试问题。
组织模型请求从当前成员设备直接访问组织的私有 Endpoint。成员设备必须具备所需的 DNS、VPN、TLS 证书和网络路由；Qixin Portal 不替成员设备转发请求。组织模型也不使用 Qixin 钱包。
如果组织使用共享密钥，密钥会提供给获得授权的成员客户端。需要立即撤销访问时，应在组织模型服务侧轮换密钥；只移除成员或停用 Portal 配置，可能要等客户端下次重新连接才会清除本机配置。
配置个人 BYOK
只有当前 Qixin 账号具备个人 BYOK 权限时，AI 设置才显示 个人 AI 服务。凭据应只输入专用字段，不要放进聊天、截图、文档或 Git。
内置订阅 Provider
- 在 个人 AI 服务 中选择添加 AI 服务。
- 选择界面列出的订阅来源和正确区域。需要 API Key 的来源，在专用字段中输入订阅方签发的 Key。
- Kimi For Coding 添加后，从该 Provider 行选择登录并完成设备码流程。Codex 会直接显示在个人 AI 服务 列表中，也通过登录连接订阅。
- 连接后点击该行的模型数量查看可用模型，再回到 AI Command Center 选择模型。
Qwen、Z.AI/GLM、MiniMax 和 MiMo 等来源的具体区域、Endpoint 和模型以当前安装版本的界面为准。内置来源的 Endpoint 由 Theseus 管理，不能当作自定义 OpenAI-compatible Provider 修改；切换区域时应添加对应区域的来源。
OpenAI-compatible Provider
- 在 个人 AI 服务 中选择添加 AI 服务 → OpenAI 兼容。
- 填写完整的 API Base URL 和 API Key；需要自定义显示名称时展开高级。
- 选择连接。连接会应用配置并立即加载模型。
- 点击该行的模型数量查看模型。模型列表支持搜索，点击模型可展开详细参数；需要手动更新时，在列表底部选择刷新模型。
- 在 AI Command Center 中明确选择模型，并发送一个不修改文件的测试问题。
Base URL 必须包含服务要求的版本路径。例如填写 https://example.com/api/v3 时，模型发现地址是 https://example.com/api/v3/models。Theseus 不会自动补写或改写 /v1、/v3 等路径。
选择该行的管理可修改连接、重新登录或退出。连接管理不提供模型刷新入口。编辑已有 Provider 时，API Key 留空会保留原有 Key，自动更新模型不会覆盖未保存的表单。保存 Provider 或刷新模型不会替当前会话更换模型；回到 AI Command Center 后仍应核对模型选择。
自动与手动刷新
所有启用且已授权的 Provider 共用 10 分钟模型目录有效期。打开 AI 设置、对话面板或模型选择器，或返回窗口时，会自动更新已过期的目录；发送消息前只检查当前使用的 Provider。不会在后台定时轮询。
模型列表中的刷新模型会立即更新对应服务，不受有效期限制。Qixin AI 和自定义 API Provider 从各自的模型接口更新；Codex 与内置订阅来源通过 Pi 的联网目录更新。组织模型仍以 Portal 已下发的授权清单为准，管理员修改清单后需要重新连接组织。
自动刷新失败时继续使用已有模型列表，不显示刷新失败提示，并在后续活动时重试；手动刷新失败会显示对应 Provider 的错误。刷新目录不会替已有对话更换模型，发送时会检查所选模型是否可用。
选择合适的模型
| 任务 | 优先考虑 |
|---|---|
| 跨多个文件、QG 与 Object 的复杂修改 | 较强推理能力和足够的上下文窗口 |
| 阅读错误或做小范围修复 | 响应速度和稳定性 |
| 图片、Vision 或页面快照审查 | 明确支持图像输入 |
| 文档解释或短文本生成 | 快速模型通常即可 |
模型选择器只显示 Provider 当前报告的能力。Provider 发布了思考等级时，菜单只显示其支持的档位。模型不可用、权限变化或 Provider 断开时，Theseus 不会静默换用另一个模型。
了解会话数据
模型来源不同，不会改变 AI Command Center 的会话保留规则：
- 完整会话历史保存在当前设备。
- 新会话以及之后发生变化的会话会归档到 Qixin 平台，包括组织模型和个人 BYOK 会话。
- 删除本地会话不会删除平台归档；平台归档不会自动到期。
- 普通用户、会话创建者和组织 OWNER/ADMIN 不能读取归档正文；平台全局管理员只能在审计约束下执行预览、单文件下载或合规删除。
- 不要提交无权上传的客户隐私数据，或必须留在现场的原始生产数据。
上线前应由组织确认数据授权、访问和删除规则。完整说明参见会话、引用与任务状态。
配置成功时你会看到
- AI 设置中显示正确的 Qixin 账户、组织模型或个人 AI 服务。
- 点击服务行的模型数量，可以搜索模型并查看所需的推理或图像能力。
- AI Command Center 能选择该模型，并完成一个只读测试问题。
- 切换 Qixin 账户或刷新 Provider 后，当前会话没有被意外清空或换模。
常见问题
看不到“个人 AI 服务”
确认当前 Qixin 账号已登录并具备个人 BYOK 权限。该入口与组织模型权限彼此独立。
Provider 已保存，但没有模型
检查登录或 API Key 状态，通过管理修正连接并保存；更新失败时使用该行的重试。一个 Provider 失败不会阻止其他正常 Provider。
OpenAI-compatible 模型刷新失败
确认 Base URL 是完整 API 根路径，并且从当前设备访问 <Base URL>/models 能返回有效模型。不要凭猜测增加或删除 /v1。同时检查代理、TLS、认证和服务返回的模型 ID。
组织模型没有出现
确认选择了正确的组织账户并选择重新连接，再让组织管理员检查 Portal 中是否已保存 Endpoint、认证方式和明确模型清单。
组织模型无法访问
从成员设备检查 DNS、VPN、TLS、认证和模型 ID。组织模型由成员设备直连，Portal 页面能打开并不代表私有 Endpoint 可达。
Qixin AI 请求失败
检查 Qixin 登录状态、当前计费账户、钱包余额和模型是否仍可用，然后重新连接账户或刷新模型。组织私有模型是否可用不取决于 Qixin 钱包余额。
Codex 显示 fetch failed
先确认当前设备的系统 HTTP(S) 代理能够访问 chatgpt.com，再重新登录或重试。不要把代理凭据贴进聊天。
安全边界
- API Key、密码和设备授权码只输入专用凭据字段。
- Provider 配置对当前桌面设备全局生效；共用设备应使用受控的系统账号和磁盘保护。
- 组织共享密钥会到达获授权的成员设备；立即撤销必须在服务侧轮换密钥。
- 不要关闭 TLS 校验或把生产密钥写进文档来绕过连接错误。
- 某个 Provider 失败时，只修复对应配置，不要删除其他正常 Provider。
下一步参见使用 AI Command Center。
本机个人配置
界面偏好、新会话模型与思考强度、个人 AI 服务的非密钥配置统一保存在 ~/.qixin/theseus/config.toml，其中 ~ 表示当前用户的主目录。设置界面的修改和手工编辑使用同一份文件；界面保存会重新格式化 TOML，不保留注释。启动时配置无效会显示错误，文件不会被自动重置。手工编辑前请完全退出应用，修改将在下次启动时生效。
此版本直接使用新的配置文件，不导入旧配置。升级后请重新设置界面偏好、个人 AI 服务和新会话模型。已保存的登录凭据与会话历史保留；不要把 API Key 或访问令牌写进此文件。