# codex-relay

**Repository Path**: sunshinewithmoonlight/codex-relay

## Basic Information

- **Project Name**: codex-relay
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codex-relay

本地 Go 中转服务，将 Codex CLI / OpenAI Responses wire API 请求转发到上游 provider，支持 DeepSeek Chat Completions 适配、Brave 网络搜索、多 provider 故障转移。

## 架构概览

```
Codex CLI / OpenAI SDK  →  codex-relay (127.0.0.1:8788)  →  上游 provider (Codex OAuth / DeepSeek / OpenAI-compatible)
                                                                └─ Brave Search API (仅 DeepSeek 路径)
```

- 使用业务 token 鉴权，不向上游暴露客户端 key
- `type: deepseek` 会自动将 hosted `web_search` 转为普通 function tool，本机调用 Brave API
- `type: codex-oauth` / `openai-compatible` 将 hosted search 原样转发给上游
- `file_search`、`code_interpreter`、`computer_use` 等 hosted tool 仍强制要求 Codex provider

### dryrun 验证

```bash
/Users/shine/.runtime/codex-relay dryrun --config ~/.runtime/codex-relay.yaml
/Users/shine/.runtime/codex-relay dryrun --strict-yaml --config ~/.runtime/codex-relay.yaml
```

默认配置加载会忽略多余字段，以便旧配置或远端配置副本仍能启动。需要验证配置已经完全迁移到当前 schema 时，使用 `dryrun --strict-yaml`；该模式会拒绝未知字段、`codex-oauth` 上的 `base_url` / `api_key`，以及旧字段 `force_reasoning`。


### Debug JSON 捕获

调试时可临时捕获请求和响应 JSON：

```bash
/Users/shine/.runtime/codex-relay debug --enable-log
/Users/shine/.runtime/codex-relay debug --status-log
/Users/shine/.runtime/codex-relay debug --disable-log
```

默认目录为 `~/log/codex-relay/log`。开启后，每个 JSON 请求和每个 JSON 响应会分别写成独立 `.json` 文件；关闭只删除开关文件，不删除已捕获文件。该功能仅用于临时排障，不会记录 Authorization header。

# 快速开始

配置文件在 `~/.runtime/codex-relay.yaml`。参见 `QUICK_DEPLOY.zh-CN.md` 和 `config/config.example.yaml`。

```bash
go test ./...
go build -o /Users/shine/.runtime/codex-relay ./cmd/codex-relay

# 首次安装 LaunchAgent
/Users/shine/.runtime/codex-relay autorun --config ~/.runtime/codex-relay.yaml

# 日常控制
/Users/shine/.runtime/codex-relay restart
/Users/shine/.runtime/codex-relay status
/Users/shine/.runtime/codex-relay logs
```

## 公开接口

| 路径 | 说明 |
|---|---|
| `POST /v1/responses` | Responses wire API，使用 `Authorization: Bearer <token>` |
| `POST /v1/chat/completions` | Chat Completions API，仅调度到 DeepSeek provider |
| `POST /chat/completions` | 同上，alias path |
| `GET /v1/models` | 当前 token profile 的 provider 列表 |
| `GET /v1/healthz` | 运维接口，含搜索状态和 provider 信息 |

## 配置要点

- `provider_order` 是显式优先级队列；失败后自动跳过并进入 cooldown
- `provider_cooldown_s` / `refresh_cooldown_s` 控制故障转移频率
- YAML 热重载自动生效；修改 `host`/`port` 需重启
- `outbound_proxy_url` 同时作用于 DeepSeek 和 Brave 请求
- `deepseek_disable_reasoning: true` 对 DeepSeek 上游发送 `thinking: {"type":"disabled"}`，避免 tool-call 场景下的 400
- `reasoning_effort` 会覆盖 Responses 请求的 `reasoning.effort`；旧字段 `force_reasoning` 默认忽略，严格模式拒绝
- `codex-oauth` provider 只需要 `auth_access_token`、`force_model`、可选 `reasoning_effort` 与 `timeout_s`；`base_url` / `api_key` 在默认模式下会被忽略，在 `dryrun --strict-yaml` 下会报错
- `dryrun --strict-yaml` 用于检查配置是否只包含当前 schema 允许的字段；不加 `--strict-yaml` 时默认忽略多余字段

- `server.stream_timeout_s` 控制长流式请求的最大持续时间；设为 `0` 表示 stream 读取阶段永不因 relay 超时而主动中断；`providers[].timeout_s` 仍控制普通请求和建立上游请求的超时。遇到 `Stream disconnected before completion: stream closed before response.completed` 时，优先把 `server.stream_timeout_s` 显式调大，例如 `1200`。
- `server.host` 支持 `127.0.0.1`、`localhost`、`0.0.0.0`；使用 `0.0.0.0` 会监听全部网卡，必须确保业务 token 和 `auth_healthz` 足够强。

## 验证

```bash
TOKEN='your-business-token'
HEALTH='your-health-token'

# 健康检查
curl -sS http://127.0.0.1:8788/v1/healthz -H "authorization: Bearer $HEALTH"

# Chat Completions
curl -sS http://127.0.0.1:8788/v1/chat/completions \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"ignored","messages":[{"role":"user","content":"Reply with exactly OK."}],"stream":false}'

# Responses + 网络搜索
curl -sS http://127.0.0.1:8788/v1/responses \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"input":"搜索当前新闻","stream":false,"tools":[{"type":"web_search_preview"}]}'
```

## 构建与发布

```bash
go test ./...
go build -ldflags "-X main.version=$(git describe --tags --always)" \
  -o /tmp/codex-relay ./cmd/codex-relay
shasum -a 256 /tmp/codex-relay
```

## 搜索支持

- `type: deepseek` provider：Relay 将 `web_search` / `web_search_preview` 转为 `web_search` function tool，DeepSeek 触发 tool call 后调用 Brave API，结果回放给模型。客户端 `tool_search` 会被静默跳过（不触发搜索、不报错）
- `type: codex-oauth` / `openai-compatible` provider：hosted search 原样转发给上游
- 未知工具类型（非 hosted web search、非客户端 `tool_search`）仍然报错，不会静默忽略