用途
Starcat Direct 的 Agent 工作台可以在内置 Loop、Codex App Server 和 DeepSeek Harness 之间切换。外部 Runtime 以本机子进程运行，不会打进 Starcat DMG。Agent 工作台需要有效的 Pro 权益。
设置 → 集成 → Agent Runtime：Codex / DeepSeek 检测状态
截图待补充 · images/screenshots/agent-workspace/runtime-setup.webp
配置总览
Codex App Server
1. 确认 Codex CLI 可用
codex app-server 时复用本机 CODEX_HOME 的现有登录态。
2. 让 Starcat 检测 Runtime 目录
打开 设置 → 集成 → Agent Runtime。- 如果 Codex 显示 Codex CLI，说明自动检测已找到本机 CLI。这个状态只表示找到了可执行文件，不代表已经登录。认证结果仍以
codex login status为准。 - 要用官方独立包，打开 Codex Releases，下载 Apple Silicon 的
codex-app-server-package-aarch64-apple-darwin.tar.gz。解压后点「选择」，选中这个 Runtime 目录。二进制可以直接位于该目录，也可以位于bin/子目录；其中必须同时有可执行的codex-app-server（或codex）和codex-code-mode-host。 - 「恢复自动检测」会清掉手工路径，再搜索
PATH、Homebrew、~/.local/bin、~/.npm-global/bin和~/.bun/bin。
选带
package 的归档。没有 package 字样的 codex-app-server-aarch64-apple-darwin.tar.gz 只有 App Server，缺 codex-code-mode-host。体积只有几 KB、文件名恰好是 codex-app-server 的那个也不是二进制包。3. 在 Agent 工作台使用
打开 Agent 工作台，选择 Codex App Server，再从 Codex 返回的目录中选择 Provider、模型和推理强度。先发送一个小任务，确认顶部 Runtime 标识和执行事件元数据都显示 Codex App Server。DeepSeek Harness
1. 检查前置条件
当前提供的 Runtime wheel 只支持 macOS arm64：2. 安装 Runtime
下载与当前 Direct 版本对应的安装脚本，检查内容后再执行。以 1.5.0 为例：deepseek-harness-runtime-bin==0.1.1rc1 安装到 ~/Library/Application Support/Starcat/Runtimes/，生成 Starcat 受限 Cordis 配置，验证三个 carrier 的签名，并自动写入正式版 Starcat Direct 的 Runtime 路径。完成后请完全退出并重新启动 Starcat。
3. 在 Starcat 配置 Provider
打开 设置 → AI，添加 DeepSeek Provider 并填写 API Key，执行连接测试，再启用至少一个 Chat 模型。API Key 只保存在 Starcat Keychain；从 Finder 启动 App 时不需要额外导出DEEPSEEK_API_KEY。
DeepSeek Harness 是 Agent 框架。已在 Starcat 中验证的 OpenAI-compatible Provider 也可以用。工作台选择的 Provider 与模型只会注入当前这次运行。
4. 检测并运行
打开 设置 → 集成 → Agent Runtime。只有 carrier、受限 Cordis 配置和已验证的 AI Provider 全部通过正式 adapter 的同一套检查时，DeepSeek 才会显示已就绪。 然后在 Agent 工作台依次选择：Runtime DeepSeek Harness → 已验证的 Starcat AI Provider → 已启用的 Chat 模型 → Reasoning 在模型没有明确支持其他级别时用 Default。 发送一个小任务并展开执行步骤，确认顶部 Runtime 标识和事件元数据都显示 DeepSeek Harness。注意 / 故障排查
Runtime unavailable
- 确认安装的是 Starcat Direct，不是 Mac App Store 版。
- 安装 Runtime 或修改路径后，完全退出并重新启动 Starcat。
- 打开 设置 → 集成 → Agent Runtime，优先按页面显示的校验错误定位，不要猜路径。
Codex 一直重试
在 Terminal 依次运行codex login status 和 codex app-server --help。如果 Terminal 可用但 Starcat 找不到 Codex，请在设置页选择包含完整 Runtime 的目录。CLI 安装通常选择 dirname "$(command -v codex)" 输出的目录。
DeepSeek 提示缺少 Provider
Provider 必须通过 设置 → AI → 测试，并启用至少一个 Chat 模型。只保存 API Key、但没有成功完成连接测试，不属于已验证的 Runtime 配置。Gatekeeper 提示 pty.node
这表示使用了错误的 Cordis 配置。重新运行 Starcat 安装脚本，并选择脚本生成的 starcat.cordis.yml。Starcat 配置故意不加载 Harness 的 bash/subprocess 插件，正常的 Agent 运行不需要 pty.node。