Repository navigation
Configuration RU
ctxray работает и без конфига: тогда он проверяет пять харнессов по умолчанию на mock-модели со встроенными лимитами. Конфиг говорит ему, какими харнессами вы пользуетесь, к какому бэкенду модели и шлюзу обращаться и каких правил ваша организация требует от контекста. Здесь перечислены все ключи с типом, значением по умолчанию и флагом или переменной окружения, которые их перекрывают.
ctxray ищет один из этих файлов в папке, где его запустили, а затем в каждой родительской вплоть до корня репозитория — папки, в которой лежит .git. Поэтому команда, запущенная из tests/ или app/, тоже находит конфиг проекта:
| Файл | Формат |
|---|---|
ctxray.config.ts |
TypeScript: конфиг — это default export |
ctxray.config.jsonc |
JSON с комментариями |
ctxray.config.json |
JSON |
Два таких файла в одной папке — ошибка, а не молчаливый выбор. --config <file> направляет любую команду к другому файлу. ctxray init пишет конфиг на TypeScript с Claude Code и Codex:
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
harnesses: {
"claude-code": {},
codex: {},
},
});defineConfig только даёт файлу типы. Модуль @mairwunnx/ctxray конфигу отдаёт сам ctxray, как и тестам, поэтому файл работает без node_modules. Конфиг на TypeScript — это код: он может читать переменные окружения или вычислять значения. Результат ctxray проверяет при загрузке и называет каждый отвергнутый ключ с его путём: ctxray.config.ts → policies[0].maxTokens.
JSON-конфиг получает автодополнение из JSON Schema, которую публикует каждый релиз:
ctxray config печатает конфиг, с которым работает прогон: все extends слиты, значения по умолчанию подставлены, переменные CTXRAY_* применены. Первая строка называет участвовавшие файлы, собственный файл проекта — последним.
ctxray configКонфиг: ctxray.config.ts
{
"harnesses": {
"claude-code": {},
"codex": {}
},
"backends": {},
"offline": false,
…
"lang": "auto",
"reportDir": ".ctxray/report"
}
Вывод сначала проходит через скрытие секретов, включая ваши redact.patterns, поэтому URL прокси с паролем печатается без пароля.
Любой ключ необязателен.
| Ключ | Тип | По умолчанию | Чем перекрывается |
|---|---|---|---|
$schema |
string |
— | — |
extends |
string или string[]
|
— | — |
harnesses |
{ [id]: HarnessSettings или false } |
claude-code, codex, gemini-cli, opencode, cursor-cli
|
--harness, CTXRAY_HARNESS
|
backends |
{ [имя]: "mock", "replay" или "real" } |
{} |
— |
upstream |
string (URL) |
собственный API провайдера | CTXRAY_UPSTREAM |
offline |
boolean |
false |
CTXRAY_OFFLINE=1 |
network |
объект, ниже | {} |
— |
concurrency |
number |
1 |
--concurrency, CTXRAY_CONCURRENCY
|
budget |
{ usd?, tokens? } |
без лимита |
--budget, CTXRAY_BUDGET_USD (доллары) |
activate |
{ min?, max?, runs? } |
min 0,8, max 0,2, runs 16 |
собственный порог или samples теста |
exactTokens |
boolean |
false |
CTXRAY_EXACT_TOKENS=1 |
prices |
{ [модель]: Price } |
встроенный список | — |
ignoreHarnessDifferences |
boolean |
false |
--ignore-harness-differences, CTXRAY_IGNORE_HARNESS_DIFFERENCES=1
|
policies |
Policy[] |
[] |
— |
redact |
{ patterns?: (string или RegExp)[] } |
только встроенные шаблоны | — |
limits |
объект | встроенные лимиты | — |
lint |
{ rules?, ignore?, errorOnWarnings?, overrides? } |
{} |
--error-on-warnings |
reporters |
string[] |
console, в CI пять репортеров |
--reporter, CTXRAY_REPORTER
|
lang |
"auto", "en" или "ru"
|
auto |
--lang, CTXRAY_LANG
|
report.langs |
string[] |
язык CLI |
--report-lang, CTXRAY_REPORT_LANG
|
report.dir |
string |
.ctxray/report |
--report-dir |
Харнессы, на которых работает ctxray test. Ключ со значением {} берёт настройки по умолчанию. Без этого ключа ctxray проверяет пять харнессов из таблицы выше. Id харнессов и их возможности перечислены на странице Harnesses.
| Настройка | Тип | По умолчанию | Значит |
|---|---|---|---|
version |
string |
тег рецепта | Диапазон версий npm, который закрепляет ctxray harness add, например 2.x
|
source |
"registry" или "system"
|
registry |
system запускает харнесс из вашего PATH вместо закреплённой сборки |
model |
string |
модель харнесса по умолчанию | Модель, с которой харнесс работает в L4–L7 |
provider |
string |
— | Провайдер, для харнесса, который знает несколько. OpenCode принимает anthropic или openai
|
userScope |
"isolated" или "inherit"
|
isolated |
inherit копирует в прогон ваши пользовательские правила, скиллы и MCP-серверы |
experimental |
boolean |
false |
Включает режимы, которые опираются на недокументированные сборки, например захват Cursor CLI |
concurrency |
number |
concurrency прогона |
Сколько сессий этого харнесса может идти одновременно, не больше лимита прогона |
false вместо настроек убирает харнесс, который добавил унаследованный конфиг:
export default defineConfig({
extends: "@acme/ctxray-config",
harnesses: { "gemini-cli": false },
});Кто отвечает харнессу в L6 и L7: mock, replay или real, как описано в Writing Tests. Конфиг не выбирает бэкенд прогона. Его выбирает --backend, затем CTXRAY_BACKEND, затем mock. backends только даёт бэкендам имена, чтобы задача CI читалась по назначению:
export default defineConfig({
backends: { pr: "replay", nightly: "real" },
});ctxray test --backend prupstream — URL вашего LLM-шлюза. Через него идут прогоны с бэкендом real, точный подсчёт токенов и ctxray gen-prompts. Без него ctxray обращается к собственному API каждого провайдера. offline: true запрещает любые сетевые запросы: ни установки харнессов, ни --backend real, ни точного подсчёта, ни ctxray gen-prompts, ни ctxray calibrate. Команда, которой нужна сеть, останавливается с кодом выхода 4 и объясняет почему, а токены считаются локально, с оценкой. --backend replay и mock работают как прежде. Шлюзу внутри закрытой сети offline не нужен: укажите его в upstream.
network описывает корпоративную сеть:
| Настройка | Тип | Значит |
|---|---|---|
proxy |
string |
URL прокси HTTP(S). Перекрывает HTTPS_PROXY и HTTP_PROXY
|
noProxy |
string[] |
Хосты в обход прокси. Перекрывает NO_PROXY
|
ca |
string[] |
PEM-файлы с дополнительными сертификатами CA, относительно конфига, который их называет. NODE_EXTRA_CA_CERTS добавляет ещё один |
systemCa |
boolean |
Доверять ещё и системному хранилищу сертификатов. То же делает NODE_USE_SYSTEM_CA=1
|
registry |
string (URL) |
Реестр npm, из которого ставятся харнессы. Перекрывает .npmrc и NPM_CONFIG_REGISTRY
|
Здесь конфиг сильнее окружения: он написан для ctxray, а переменные — для всех программ на машине. Шлюзы, прокси, сертификаты и закрытые сети описаны на странице Enterprise.
Прогон с бэкендом real перестаёт обращаться к модели, когда потратит budget.usd долларов или budget.tokens токенов. Тесты, которые начинаются после этого, пропускаются с пометкой «бюджет исчерпан». --budget <usd> и CTXRAY_BUDGET_USD задают сумму в долларах для одного прогона.
ctxray знает цены моделей, с которыми его адаптеры работают по умолчанию. prices добавляет другие или меняет известные, в долларах США за миллион токенов:
export default defineConfig({
prices: {
"corp-sonnet": { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 },
},
});Если cacheRead и cacheWrite не указаны, они стоят как input. Модель без цены всё равно работает, а отчёт показывает её токены без стоимости.
Тест L6 или L7 запускает харнесс один раз на каждый промпт и сэмпл. По умолчанию ctxray запускает эти сессии одну за другой, чтобы прогон поместился на маленьком раннере CI. concurrency разрешает запускать несколько сразу: прогон идёт быстрее, а памяти нужно больше — по сессии на каждую лишнюю (системные требования).
Собственный concurrency харнесса ограничивает его сильнее — для того, кто ест много памяти или упирается в лимиты запросов своего провайдера:
export default defineConfig({
concurrency: 4,
harnesses: { opencode: { concurrency: 2 }, codex: {} }, // Codex — по 4 сразу, OpenCode — по 2
});--concurrency <число> и CTXRAY_CONCURRENCY задают лимит для одного прогона. L4 и L5 всегда идут по одной сессии.
Значения по умолчанию для L6 Activate во всех тестах проекта. min — доля прогонов, в которых скилл или правило должны загрузиться для toActivate(), по умолчанию 0,8. max — наибольшая доля, в которой они могут загрузиться для .not.toActivate(), по умолчанию 0,2. runs — сколько прогонов тест без samples даёт каждой группе промптов.
Без runs ctxray берёт наименьшее число прогонов, которым можно доказать оба порога: 16 для значений по умолчанию, 35, если min равен 0,9. При меньшем числе даже модель, которая ни разу не ошиблась, осталась бы с результатом «не определён». Порог, который тест передаёт в toActivate({ … }), и собственный samples теста по-прежнему важнее. Интервал, из которого берутся эти числа, описан в Writing Tests.
export default defineConfig({
activate: { min: 0.9 }, // runs сам вырастет до 35
});Локальный подсчёт — это оценка, и рядом с ним стоит ≈. exactTokens: true отправляет захваченные запросы в эндпоинт подсчёта провайдера через upstream и ваш ключ, и числа в L4–L7 становятся точными. Каким токенизатором оценивается каждый харнесс, рассказано на странице Harnesses.
L1 предупреждает, когда харнессы одного прогона получают разные инструкции или скиллы: правило, которое читает только Claude Code, оставляет Codex без него. Если так и задумано, ignoreHarnessDifferences: true выключает эти предупреждения harness-differences. То же самое для отдельной проверки делает lint.rules, см. Policies.
policies хранит правила вашей организации для контекста, их проверяют L2 и L4. limits задаёт лимиты размера скиллов, команд и файлов инструкций, а lint — уровень каждой проверки L1. Все три описаны на странице Policies.
ctxray прячет API-ключи, токены, email, номера телефонов и карт до того, как что-либо попадёт на диск. redact.patterns добавляет ваши шаблоны: RegExp в конфиге на TypeScript, его исходник строкой в JSON.
export default defineConfig({
redact: { patterns: [/ACME-[0-9]{6}/] },
});Что именно скрывает ctxray, перечислено на странице Reporters and Reports.
reporters выбирает, куда пишет ctxray test: console, html, junit, allure, json и markdown. Без него локальный прогон печатает в консоль. В CI он пишет console, json, junit, markdown и html. report.dir — куда ложатся файлы отчётов, относительно корня проекта. report.langs перечисляет языки HTML-отчёта, или all. Каждый вывод описан на странице Reporters and Reports.
Язык CLI: auto следует за системой, en и ru закрепляют язык. Полный порядок выбора языка — на странице Localization.
extends строит конфиг поверх других: пути или npm-пакета, который ищется от папки конфига. Подходит и список:
export default defineConfig({
extends: ["@acme/ctxray-config", "./ctxray.ci.ts"],
harnesses: { "claude-code": {}, codex: {} },
});ctxray загружает конфиги в глубину, так что каждый идёт после тех, от которых наследуется. Поздние элементы списка сильнее ранних, а сам файл сильнее их всех. Конфиги, которые наследуют друг друга по кругу, — ошибка.
Конфиги сливаются по таким правилам:
| Что | Как сливается |
|---|---|
Объекты: harnesses, network, budget, activate, limits, lint.rules
|
Ключ за ключом |
Массивы и простые значения: reporters, network.ca
|
Более поздний конфиг заменяет их |
policies |
По id: политика с унаследованным id сливается с ним поле за полем, новая встаёт в конец |
redact.patterns |
Складываются. Убрать унаследованный шаблон конфиг не может |
lint.ignore, lint.overrides
|
Складываются, унаследованные первыми, поэтому собственные переопределения проекта побеждают |
Путь в network.ca
|
Остаётся относительным к конфигу, который его называет |
После слияния политика должна что-то проверять. Политика без maxTokens, denyMcp, requireMcp и requireFiles останавливает прогон. Общий конфиг, опубликованный пакетом, показан на странице Enterprise, а как проект меняет унаследованную политику — на странице Policies.
Флаг сильнее переменной CTXRAY_*, переменная сильнее конфига, конфиг сильнее значения по умолчанию. CI задаёт переменные для каждой задачи, а файл конфига общий для всех. Два вида настроек работают иначе. offline, exactTokens и ignoreHarnessDifferences включаются, если этого хочет переменная или конфиг. А network сильнее общесистемных переменных прокси и сертификатов, как сказано выше.
| Настройка | Флаг | Переменная | Конфиг | По умолчанию |
|---|---|---|---|---|
| Харнессы | --harness |
CTXRAY_HARNESS |
harnesses |
пять харнессов |
| Бэкенд | --backend |
CTXRAY_BACKEND |
имена из backends
|
mock |
| Слои | --layer |
CTXRAY_LAYER |
— | L1–L7 |
| Upstream | — | CTXRAY_UPSTREAM |
upstream |
API провайдера |
| Сессий одновременно | --concurrency |
CTXRAY_CONCURRENCY |
concurrency |
1 |
| Бюджет в долларах | --budget |
CTXRAY_BUDGET_USD |
budget.usd |
нет |
| Репортеры | --reporter |
CTXRAY_REPORTER |
reporters |
console, в CI больше |
| Языки отчёта | --report-lang |
CTXRAY_REPORT_LANG |
report.langs |
язык CLI |
| Папка отчётов | --report-dir |
— | report.dir |
.ctxray/report |
| Язык CLI | --lang |
CTXRAY_LANG |
lang |
язык системы |
| Предупреждения роняют прогон | --error-on-warnings |
— | lint.errorOnWarnings |
false |
ctxray читает эти переменные. Переключатель считается включённым при любом значении, кроме пустой строки, 0 и false.
| Переменная | Значит |
|---|---|
CTXRAY_HARNESS |
Харнессы для ctxray test через запятую |
CTXRAY_BACKEND |
mock, replay, real или имя из backends
|
CTXRAY_LAYER |
Слои, например L1-L5, L3 или 3-5
|
CTXRAY_REPORTER |
Репортеры через запятую |
CTXRAY_REPORT_LANG |
Языки HTML-отчёта через запятую, или all
|
CTXRAY_LANG |
Язык CLI: en или ru
|
CTXRAY_UPSTREAM |
URL LLM-шлюза. Перекрывает upstream
|
CTXRAY_UPSTREAM_KEY |
Ключ, который ctxray отправляет в upstream для любого провайдера. Сильнее ключей провайдеров |
CTXRAY_OFFLINE |
Переключатель: никаких сетевых запросов |
CTXRAY_CONCURRENCY |
Сколько сессий харнесса тест L6 или L7 запускает одновременно |
CTXRAY_BUDGET_USD |
Сколько долларов может потратить настоящий прогон |
CTXRAY_EXACT_TOKENS |
Переключатель: считать токены эндпоинтом провайдера |
CTXRAY_IGNORE_HARNESS_DIFFERENCES |
Переключатель: не предупреждать, что харнессы получают разные инструкции |
CTXRAY_CACHE_DIR |
Папка кеша харнессов, см. Harnesses |
CTXRAY_CACHE_DIRS |
Слои кеша, через разделитель как в PATH: установки берёт первый доступный для записи |
CTXRAY_DEBUG |
Переключатель: строка, которой нет в выбранном языке, сообщает об этом |
Ещё ctxray читает ключи провайдеров ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY и CLAUDE_CODE_OAUTH_TOKEN, сетевые переменные HTTPS_PROXY, HTTP_PROXY, NO_PROXY, NODE_EXTRA_CA_CERTS и NODE_USE_SYSTEM_CA и переменные реестра npm. Каждая описана на странице Enterprise. CI, GITLAB_CI и GITHUB_ACTIONS переводят ctxray в режим CI, как рассказано в CI Integration.
Каждый релиз прикладывает JSON Schema для файлов, которые пишете вы, и файлов, которые пишет ctxray. bun run schemas собирает те же файлы из исходников в dist/schemas.
| Ассет | Описывает |
|---|---|
config.schema.json |
ctxray.config.json и .jsonc
|
tests.schema.json |
декларативные тесты *.ctxray.jsonc
|
lockfile.schema.json |
ctxray.lock |
report.schema.json |
.ctxray/report/report.json |
loadout.schema.json |
снапшот Loadout |
session.schema.json |
захваченная сессия, ход за ходом |
inspection.schema.json |
ctxray inspect --json |
exchange.schema.json |
одна строка файла трассы |
Они лежат по адресу https://github.com/MairwunNx/ctxray/releases/latest/download/<имя>.schema.json. Если редактор должен следовать за вашей версией, а не за самой свежей, укажите версию в URL.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие
{ "$schema": "https://github.com/MairwunNx/ctxray/releases/latest/download/config.schema.json", "harnesses": { "claude-code": {}, "codex": {} }, "policies": [{ "id": "context-budget", "maxTokens": { "total": 25000 } }] }