121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
# OpenAI 兼容 API 环境变量
|
||
|
||
CST-Agent 使用 **OpenAI Chat Completions** 协议（`POST {base}/chat/completions`，SSE 流式），
|
||
可对接官方 OpenAI、DeepSeek、MiniMax，以及其它兼容网关。
|
||
|
||
## Provider 预设
|
||
|
||
`--provider NAME`（或 `CST_PROVIDER`，或 TUI 里的 `/provider`）一次性给出 base 和默认模型。
|
||
不传时沿用上次使用的 provider（记在配置目录的 `settings.json`）。
|
||
|
||
| provider | API Base | 默认模型 | Key 变量 |
|
||
|---|---|---|---|
|
||
| `minimax`（默认） | `https://api.minimax.cn/v1` | `MiniMax-M2.7` | `MINIMAX_API_KEY` |
|
||
| `deepseek` | `https://api.deepseek.com/v1` | `deepseek-flash`（另有 `deepseek-v4-pro`） | `DEEPSEEK_API_KEY` |
|
||
| `kimi` | `https://api.moonshot.ai/v1` | `kimi-k3`（另有 `kimi-k2.6`、`kimi-k2.7-code`） | `MOONSHOT_API_KEY` |
|
||
| `kimi-code` | `https://api.kimi.ai/coding/v1` | `k3`（另有 `k3-256k`、`kimi-for-coding`、`kimi-for-coding-highspeed`） | `KIMI_API_KEY` |
|
||
| `openai` | `https://api.openai.com/v1` | `gpt-4.1-mini` | `OPENAI_API_KEY` |
|
||
| `teamorouter` | `https://api.teamorouter.com/v1` | 登录后自动取 `/models` 第一个（`/model` 可换） | `TEAMOROUTER_API_KEY` |
|
||
|
||
显式给出的 `--api-base` / `--model` / 下表中的环境变量优先于预设。
|
||
|
||
## 解析顺序
|
||
|
||
| 项 | 优先级（高 → 低） |
|
||
|---|---|
|
||
| Key | `--api-key`（**只用于本次进程，不写盘**）→ 该 provider 已保存的 key → provider 的 Key 变量 → `CST_API_KEY` → TUI 弹出遮罩输入框（输入后保存） |
|
||
| Base（含 `/v1`，不带 `/chat/completions`） | `--api-base` → `CST_API_BASE` → `OPENAI_BASE_URL` → `OPENAI_API_BASE` → 预设 |
|
||
| Model | `--model` → `CST_MODEL` → `OPENAI_MODEL` → 该 provider 上次使用的模型 → 预设 |
|
||
| 推理强度 | `--effort` → `CST_EFFORT` → 上次使用 → `medium`（low / medium / high / max） |
|
||
|
||
Kimi 的 K3 请求使用 `reasoning_effort`；K2.6/K2.7 使用 `thinking`，并在后续请求中回传 `reasoning_content`。默认发送 Kimi 1 小时隐式 prompt cache 提示，可用 `CST_KIMI_CACHE_TTL=5m|1h` 调整，或用 `CST_NO_CACHE_HINTS=1` 关闭。
|
||
|
||
当 provider 为 Kimi 或 DeepSeek 时，`web_search` 和 `web_fetch` 使用对应的官方联网 Search/Fetch API；其它 provider 使用通用 URL 抓取。
|
||
|
||
`kimi-code` 使用 Kimi Code 的 OpenAI-compatible API。它和按量计费的 `kimi` 开放平台使用不同的 Base URL 与 API Key，不能混用。
|
||
|
||
key 按 provider 保存在 credentials 文件（权限 0600），每行 `<provider>.api_key=...`；
|
||
TUI 里 `/key` 更换，命令行 `--ask-key` 输入（不回显）：
|
||
- Linux/macOS/Termux：`$XDG_CONFIG_HOME/cst-agent/credentials`（默认 `~/.config/cst-agent/`）
|
||
- Windows：`%APPDATA%\cst-agent\credentials`
|
||
|
||
旧版只有一行 `api_key=` 的文件仍可读：按其中的 `api_base` 归到对应 provider（没有 `api_base` 时视为 MiniMax）。
|
||
|
||
## 示例
|
||
|
||
### DeepSeek
|
||
|
||
```bash
|
||
cst-agent --provider deepseek # 首次会询问 key；默认 deepseek-flash
|
||
cst-agent --provider deepseek --model deepseek-v4-pro -e high # 推理内容显示为 Thought
|
||
```
|
||
|
||
### Kimi
|
||
|
||
```bash
|
||
cst-agent --provider kimi # 默认 kimi-k3
|
||
cst-agent --provider kimi --model kimi-k2.6 # K2 thinking 模式
|
||
```
|
||
|
||
### Kimi Code
|
||
|
||
```bash
|
||
cst-agent --provider kimi-code # 默认 k3
|
||
cst-agent --provider kimi-code --model k3-256k
|
||
```
|
||
|
||
### OpenAI 官方
|
||
|
||
```bash
|
||
cst-agent --provider openai
|
||
```
|
||
|
||
### MiniMax（默认）
|
||
|
||
```bash
|
||
cst-agent --provider minimax
|
||
```
|
||
|
||
### 任意兼容网关
|
||
|
||
```bash
|
||
export OPENAI_API_KEY='...'
|
||
export OPENAI_BASE_URL='https://your-gateway.example/v1'
|
||
export OPENAI_MODEL='your-model'
|
||
./cst-agent --headless --prompt 'ping' --workspace .
|
||
```
|
||
|
||
网关不支持 `stream_options.include_usage` 时设 `CST_NO_STREAM_USAGE=1`。
|
||
|
||
## 其它环境变量
|
||
|
||
| 变量 | 说明 |
|
||
|---|---|
|
||
| `CST_PROTOCOL` | 工具调用协议：`native-eos`（默认）/ `native-inc` / `ctl` / `ctl-heredoc` / `xml` |
|
||
| `CST_MAX_STEPS` | 每个用户回合最多调用模型几次（默认 30） |
|
||
| `CST_TOOL_OUT_CAP` | 单个工具输出发给模型的字节上限（默认 16384） |
|
||
| `CST_CTX_WINDOW` | 发给模型的最近非 system 消息条数（默认 80） |
|
||
| `CST_SHELL_TIMEOUT` | `run_shell` 超时秒数（默认不限，Ctrl+C / 停止按钮仍可随时中断） |
|
||
| `CST_METRICS=0` / `CST_METRICS_PATH` | 关闭 / 指定计时埋点 JSONL |
|
||
| `CST_RECORD_SSE` / `CST_REPLAY_SSE` | 录制 / 回放原始 SSE 流目录；`CST_REPLAY_CHUNK` 控制回放分块字节数 |
|
||
| `CST_MODELS` | `/model` 可选列表，`:` 或 `,` 分隔 |
|
||
| `CST_AUTO_APPROVE=1` | 自动允许 shell/写文件（= `--approval yolo`；headless 默认开启） |
|
||
| `CST_APPROVAL` | 审批模式 `ask` / `auto`（默认）/ `yolo` |
|
||
| `CST_SANDBOX=off` | 关闭 run_shell 沙箱（Landlock / seccomp / macOS sandbox），`auto` 回落到只读白名单；`landlock` / `seccomp` 只允许该种 |
|
||
| `CST_SHELL` | shell 解释器路径（覆盖 busybox/`sh`） |
|
||
| `CST_EXE_DIR` | 可执行文件目录（Termux 旁路 busybox 时有用） |
|
||
|
||
网络：连接超时 30 秒；300 秒内无数据视为超时；429 / 5xx / 连接错误在尚未收到任何内容时自动重试 3 次（1s、2s、4s 退避）。
|
||
|
||
## CLI 对照
|
||
|
||
```text
|
||
--provider NAME ← CST_PROVIDER
|
||
--api-base URL ← CST_API_BASE / OPENAI_BASE_URL
|
||
--api-key KEY ← 已保存的 key / <provider key 变量> / CST_API_KEY
|
||
--model NAME ← CST_MODEL / OPENAI_MODEL
|
||
--effort LEVEL ← CST_EFFORT
|
||
--protocol P ← CST_PROTOCOL
|
||
--max-steps N ← CST_MAX_STEPS
|
||
```
|