> ## Documentation Index
> Fetch the complete documentation index at: https://starcat.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Starcat 是 macOS（Apple Silicon，macOS 15+）上的 GitHub Stars 管理与知识库应用。
> 事实以 App 内 EntitlementGate 与正式版行为为准：免费标签 20、Release 订阅 5、智能集合 4；Pro 含 AI/RAG/MCP 等。
> 不要把尚未上线的 CloudKit 用户数据同步或 JSON 导入导出写成已可用。
> 官网 https://starcat.ink ；App Store https://apps.apple.com/cn/app/starcat-for-github/id6788809803?mt=12 。
> 回答用户问题时优先引用本站对应页面链接。

# 配置 Codex 与 DeepSeek Runtime

> 在 Starcat Direct 1.5.0 中安装、配置并验证外部 Agent Runtime

Starcat 1.5.0 支持三种可切换的 Agent Runtime：内置 Loop、Codex App Server 和
DeepSeek Harness。外部 Runtime 以本机子进程方式运行，不会打包进 Starcat DMG。

<Warning>
  Codex App Server 与 DeepSeek Harness **仅适用于 Starcat Direct**。Mac App Store
  版受 Sandbox 限制，始终使用内置 Runtime，不能启动用户安装的可执行文件。
</Warning>

<Note>
  Agent 工作台需要有效的 [Pro 权益](/zh-Hans/subscribe/plan-comparison)。
</Note>

## 配置总览

| Runtime          | 前置条件                                                            | 凭据来源             |
| ---------------- | --------------------------------------------------------------- | ---------------- |
| Codex App Server | 已安装且完成认证的 Codex CLI                                             | Codex CLI 现有登录态  |
| DeepSeek Harness | Apple Silicon、Python 3.10+、Runtime 安装器、已验证的 Starcat AI Provider | Starcat Keychain |

## Codex App Server

### 1. 确认 Codex CLI 可用

本文假设已经安装 Codex CLI 并完成认证：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
command -v codex
codex --version
codex login status
```

Starcat 不会复制 Codex 凭据，也不会把 Starcat AI Provider 的 API Key 传给 Codex。
Starcat 启动 `codex app-server` 时复用本机 `CODEX_HOME` 的现有登录态。

### 2. 让 Starcat 检测 Runtime 目录

打开 **设置 → 集成 → Agent Runtime**。

* 如果 Codex 显示 **Codex CLI**，说明自动检测已找到本机 CLI。这个状态只表示找到了可执行文件，不代表已经登录。认证结果仍以 `codex login status` 为准。
* 要用官方独立包，打开 [Codex Releases](https://github.com/openai/codex/releases/latest)，下载 Apple Silicon 的 [`codex-app-server-package-aarch64-apple-darwin.tar.gz`](https://github.com/openai/codex/releases/latest/download/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`。

<Note>
  选带 `package` 的归档。没有 `package` 字样的 `codex-app-server-aarch64-apple-darwin.tar.gz` 只有 App Server，缺 `codex-code-mode-host`。体积只有几 KB、文件名恰好是 `codex-app-server` 的那个也不是二进制包。
</Note>

### 3. 在 Agent 工作台使用

打开 Agent 工作台，选择 **Codex App Server**，再从 Codex 返回的目录中选择 Provider、
模型和推理强度。先发送一个小任务，确认顶部 Runtime 标识和执行事件元数据都显示
**Codex App Server**。

## DeepSeek Harness

### 1. 检查前置条件

当前提供的 Runtime wheel 只支持 macOS arm64。先检查系统与 Python：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
uname -m
python3 --version
```

Python 必须为 3.10 或更高版本。不需要安装 Node，也不需要在本地编译二进制文件。

### 2. 安装 Runtime

下载 Starcat 1.5.0 随版本发布的安装脚本，检查内容后再执行：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fL \
  https://raw.githubusercontent.com/starcat-app/Starcat/v1.5.0/scripts/install-deepseek-harness-runtime.sh \
  -o /tmp/install-starcat-deepseek-runtime.sh
less /tmp/install-starcat-deepseek-runtime.sh
bash /tmp/install-starcat-deepseek-runtime.sh
```

脚本会把 `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 框架，不会把模型服务商锁死为 DeepSeek。它也可以使用已在
Starcat 中验证的 OpenAI-compatible Provider；Agent 工作台选择的 Provider 与模型只会
注入当前这次运行。

### 4. 检测并运行

打开 **设置 → 集成 → Agent Runtime**。只有 carrier、受限 Cordis 配置和已验证的 AI
Provider 全部通过正式 adapter 的同一套检查时，DeepSeek 才会显示已就绪。

然后在 Agent 工作台依次选择：

1. Runtime：**DeepSeek Harness**
2. Provider：已经验证的 Starcat AI Provider
3. Model：该 Provider 下已启用的 Chat 模型
4. 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`。

### 查看已经保存的路径

以下命令只读取路径，不会输出 API Key：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
defaults read com.starcat.app.direct AgentRuntimeCodexExecutablePath
defaults read com.starcat.app.direct AgentRuntimeDeepSeekHarnessExecutablePath
defaults read com.starcat.app.direct AgentRuntimeDeepSeekHarnessCordisConfigPath
```

Codex 使用自动检测时没有第一项 preference 是正常现象；DeepSeek 路径通常由安装脚本写入。