Skip to content

Configuration RU

Pavel Erokhin edited this page Nov 20, 2026 · 4 revisions

English version

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, которую публикует каждый релиз:

{
  "$schema": "https://github.com/MairwunNx/ctxray/releases/latest/download/config.schema.json",
  "harnesses": { "claude-code": {}, "codex": {} },
  "policies": [{ "id": "context-budget", "maxTokens": { "total": 25000 } }]
}

Итоговый конфиг

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

harnesses

Харнессы, на которых работает 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 },
});

backends

Кто отвечает харнессу в L6 и L7: mock, replay или real, как описано в Writing Tests. Конфиг не выбирает бэкенд прогона. Его выбирает --backend, затем CTXRAY_BACKEND, затем mock. backends только даёт бэкендам имена, чтобы задача CI читалась по назначению:

export default defineConfig({
  backends: { pr: "replay", nightly: "real" },
});
ctxray test --backend pr

upstream, offline, network

upstream — 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.

budget и prices

Прогон с бэкендом 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. Модель без цены всё равно работает, а отчёт показывает её токены без стоимости.

concurrency

Тест 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 всегда идут по одной сессии.

activate

Значения по умолчанию для 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

Локальный подсчёт — это оценка, и рядом с ним стоит ≈. exactTokens: true отправляет захваченные запросы в эндпоинт подсчёта провайдера через upstream и ваш ключ, и числа в L4–L7 становятся точными. Каким токенизатором оценивается каждый харнесс, рассказано на странице Harnesses.

ignoreHarnessDifferences

L1 предупреждает, когда харнессы одного прогона получают разные инструкции или скиллы: правило, которое читает только Claude Code, оставляет Codex без него. Если так и задумано, ignoreHarnessDifferences: true выключает эти предупреждения harness-differences. То же самое для отдельной проверки делает lint.rules, см. Policies.

policies, limits, lint

policies хранит правила вашей организации для контекста, их проверяют L2 и L4. limits задаёт лимиты размера скиллов, команд и файлов инструкций, а lint — уровень каждой проверки L1. Все три описаны на странице Policies.

redact

ctxray прячет API-ключи, токены, email, номера телефонов и карт до того, как что-либо попадёт на диск. redact.patterns добавляет ваши шаблоны: RegExp в конфиге на TypeScript, его исходник строкой в JSON.

export default defineConfig({
  redact: { patterns: [/ACME-[0-9]{6}/] },
});

Что именно скрывает ctxray, перечислено на странице Reporters and Reports.

reporters и report

reporters выбирает, куда пишет ctxray test: console, html, junit, allure, json и markdown. Без него локальный прогон печатает в консоль. В CI он пишет console, json, junit, markdown и html. report.dir — куда ложатся файлы отчётов, относительно корня проекта. report.langs перечисляет языки HTML-отчёта, или all. Каждый вывод описан на странице Reporters and Reports.

lang

Язык CLI: auto следует за системой, en и ru закрепляют язык. Полный порядок выбора языка — на странице Localization.

extends

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

Каждый релиз прикладывает 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.

Clone this wiki locally