---
description: "将 VTCode 接入在问 API，密钥可存系统钥匙串不落盘。"
---

# 接入 VTCode

> [VTCode](https://github.com/vinhnx/vtcode)（vtcode）是开源终端编程 Agent（Rust 编写），核心特色是 **LLM 原生代码理解与专用代码搜索工具链**：内置 ripgrep 全文搜索、ast-grep 符号图谱、模糊发现与项目索引，并支持 OS 原生沙箱、多供应商（26+）与本地推理。API Key 可安全存入系统钥匙串（OS keyring / 加密文件），不会明文落盘到配置文件。

## 安装

macOS / Linux 一键安装（同时安装 ripgrep、ast-grep 依赖）：

```bash
curl -fsSL https://raw.githubusercontent.com/vinhnx/vtcode/main/scripts/install.sh | bash
```

Homebrew 方式：

```bash
brew trust vinhnx/tap
brew install vinhnx/tap/vtcode
```

安装后可用 `vtcode --version` 验证。

## 配置步骤

### 1. 配置 `~/.vtcode/vtcode.toml`

打开 `~/.vtcode/vtcode.toml`（文件不存在则创建），写入以下内容：

```toml
[agent]
provider = "zaiwenai"
default_model = "grok-4.6"
reasoning_effort = "medium"

[[custom_providers]]
api_key_env = "ZAIWENAI_API_KEY"
base_url = "https://oneapi.zaiwenai.com/v1"
api_format = "openai-responses"
context_window = 256000
display_name = "在问 AI"
model = "gpt-5.6-luna"
models = [
    "gpt-5.6-terra",
    "gpt-5.6-luna",
    "grok-4.6",
]
name = "zaiwenai"
```

如果该文件已有其他自定义供应商配置，请先备份，再手动合并 `[agent]` 与 `[[custom_providers]]` 节点。

也可以使用以下辅助命令自动备份并写入（macOS、Linux 或 WSL）：

```bash
CONFIG_DIR="$HOME/.vtcode"
mkdir -p "$CONFIG_DIR"
CONFIG_PATH="$CONFIG_DIR/vtcode.toml"
[ ! -f "$CONFIG_PATH" ] || cp "$CONFIG_PATH" "$CONFIG_PATH.bak"
printf '%s\n' '上面的完整 TOML 内容' > "$CONFIG_PATH"
```

Windows PowerShell：

```powershell
$vtcodeDir = Join-Path $HOME ".vtcode"
New-Item -ItemType Directory -Force -Path $vtcodeDir | Out-Null
$configPath = Join-Path $vtcodeDir "vtcode.toml"
if (Test-Path $configPath) { Copy-Item $configPath "$configPath.bak" -Force }
# 用 here-string 写入上面的完整 TOML 内容
@'
[agent]
provider = "zaiwenai"
# ...完整内容...
'@ | Set-Content -Encoding utf8 $configPath
```

### 2. 将 API Key 存入安全存储

vtcode 要求供应商先存在于配置中，因此请先完成第 1 步，再在终端执行以下命令（把 `sk-你的在问APIKEY` 替换为你的密钥），Key 会被存入系统钥匙串：

```bash
printf '%s\n' 'sk-你的在问APIKEY' | vtcode secret add zaiwenai --key-name ZAIWENAI_API_KEY
```

Windows PowerShell：

```powershell
'sk-你的在问APIKEY' | vtcode secret add zaiwenai --key-name ZAIWENAI_API_KEY
```

::: tip 说明
- `zaiwenai` 是 provider 名，`--key-name ZAIWENAI_API_KEY` 指定环境变量身份，两者需要与第 1 步 `vtcode.toml` 中的配置保持一致
- Key 只保存在安全存储中，**不会**写入 `vtcode.toml` 或 workspace 环境文件
- 执行 `vtcode secret list` 可查看各 provider 的存储状态
:::

::: tip 快捷方式：一条命令完成两步
也可以直接用下面的命令一次性完成「写入配置（添加供应商）+ 存储 API Key」，已有配置文件会自动备份（macOS、Linux 或 WSL）：

```bash
CONFIG_DIR="$HOME/.vtcode"
mkdir -p "$CONFIG_DIR"
CONFIG_PATH="$CONFIG_DIR/vtcode.toml"
[ ! -f "$CONFIG_PATH" ] || cp "$CONFIG_PATH" "$CONFIG_PATH.bak"
printf '%s\n' '上面的完整 TOML 内容' > "$CONFIG_PATH"
printf '%s\n' 'sk-你的在问APIKEY' | vtcode secret add zaiwenai --key-name ZAIWENAI_API_KEY
```

Windows PowerShell：

```powershell
$vtcodeDir = Join-Path $HOME ".vtcode"
New-Item -ItemType Directory -Force -Path $vtcodeDir | Out-Null
$configPath = Join-Path $vtcodeDir "vtcode.toml"
if (Test-Path $configPath) { Copy-Item $configPath "$configPath.bak" -Force }
# 用 here-string 写入上面的完整 TOML 内容
@'
[agent]
provider = "zaiwenai"
# ...完整内容...
'@ | Set-Content -Encoding utf8 $configPath
'sk-你的在问APIKEY' | vtcode secret add zaiwenai --key-name ZAIWENAI_API_KEY
```

命令先写入 `~/.vtcode/vtcode.toml`（添加供应商），再存储 API Key。
:::

### 3. 验证

在项目目录启动 VTCode：

```bash
vtcode
```

启动后可用 `/model` 切换模型（`zaiwenai / GPT-5.6-Terra`、`zaiwenai / GPT-5.6-Luna`、`zaiwenai / grok-4.6`）。

::: tip 配置说明
- `api_key_env = "ZAIWENAI_API_KEY"`（provider 级）：该端点的凭据身份作用域，与第 2 步 `vtcode secret add zaiwenai --key-name ZAIWENAI_API_KEY` 存储的 Key 按 `(name, api_key_env)` 一一对应
- `api_format = "openai-responses"`（provider 级）：在问平台提供 OpenAI Responses 协议（`/v1/responses`），与 Codex 的 `wire_api = "responses"` 一致，能正确下发推理强度参数；该字段是 `[[custom_providers]]` 端点的能力声明，`[agent]` 段无需填写
- `context_window = 256000`：上下文窗口配置为 256K，低于 OpenAI 短上下文计费阈值（272K），避免触发长上下文倍率计费
- 辅助命令会在覆盖前将已有文件备份为 `.bak`
:::