Repository navigation
Enterprise RU
В корпоративной сети ctxray работает так же, как на ноутбуке: за прокси, со своими CA-сертификатами, через LLM-шлюз, из внутреннего npm-реестра или вовсе без сети. Здесь описано, как настроить каждый из этих случаев и что ctxray обещает насчёт ваших данных.
ctxray doctor проверяет, что нужно слоям L4 и выше на этой машине: git, сеть, кеш и закреплённые харнессы. Запускайте его первым делом на каждом новом раннере и после каждого изменения сети:
$ ctxray doctor --lang en
System
· ctxray 0.1.0 on linux-x64-glibc
✓ git 2.54.0
✓ Node.js 26.13.1
· No sandbox on this system: run L4 and up in a container, as CI does
Network
✓ Proxy http://***@proxy.corp.example:3128/
! NO_PROXY entry “*.corp.example” doesn't work in Bun as in curl: write “.corp.example”
✓ CA certificates from /etc/ssl/corp/root.pem
✓ npm registry https://npm.corp.example/
✓ The registry answers (200)
Harnesses
✓ Cache /home/ci/.cache/ctxray: 2 builds, 512 MB
✓ Lockfile ctxray.lock
✓ claude-code 2.1.325 installed
✓ codex 0.169.0 installed
1 warning
Ошибка завершает команду с кодом 4, предупреждение только говорит, что может пойти не так. Пароль прокси в выводе не появляется: вывод попадает в логи CI.
| Раздел | Что проверяет |
|---|---|
| System | git (L4 и выше копируют проект через него), Node.js (без него не стартуют MCP-серверы на Node), настройки администратора в /etc/claude-code, /etc/codex или их аналогах на macOS и Windows, которые ни один прогон не изолирует, и песочницу |
| Network | прокси, записи NO_PROXY, которые Bun читает не так, как curl, каждый CA-файл, npm-реестр и отвечает ли он |
| Harnesses | доступен ли кеш на запись, кеши только для чтения, ctxray.lock против конфига и каждый закреплённый харнесс на этой платформе |
К провайдеру модели обращаются только слои L6 и L7 с --backend real, точный подсчёт токенов (exactTokens), ctxray gen-prompts и ctxray calibrate. Всё остальное остаётся на машине.
По умолчанию ctxray отправляет каждый запрос в API самого провайдера. Чтобы ходить через корпоративный шлюз, укажите его один раз в конфиге или в окружении — окружение важнее:
export default defineConfig({
upstream: "https://llm-gateway.corp.example",
});export CTXRAY_UPSTREAM=https://llm-gateway.corp.examplectxray дописывает к этому URL путь харнесса без изменений: /v1/messages для Anthropic, /v1/responses или /v1/chat/completions для OpenAI, /v1beta/models/… для Gemini. Значит, шлюз должен отдавать API каждого провайдера под одним базовым URL.
Настоящего ключа у харнесса никогда нет. ctxray даёт ему фиктивный ключ, а прокси подставляет настоящий на выходе:
| Переменная | Куда уходит | Как |
|---|---|---|
CTXRAY_UPSTREAM_KEY |
во все протоколы, раньше ключей провайдеров | в заголовке своего протокола |
ANTHROPIC_API_KEY |
Anthropic Messages | x-api-key |
OPENAI_API_KEY |
OpenAI Responses и Chat Completions | Authorization: Bearer |
GEMINI_API_KEY |
Gemini | x-goog-api-key |
CLAUDE_CODE_OAUTH_TOKEN |
Anthropic, если ни один ключ выше не задан |
Authorization: Bearer с OAuth-бетой |
CLAUDE_CODE_OAUTH_TOKEN — это токен, который печатает claude setup-token, для команд, у которых Claude Code работает по подписке. Если ключа нет совсем, ctxray его не отправляет, и upstream отвечает 401 своими словами.
ctxray читает привычные переменные, сначала в нижнем регистре, как Bun: HTTPS_PROXY, HTTP_PROXY и NO_PROXY. Конфиг их перекрывает: он написан для ctxray, а переменные — для всех программ сразу:
export default defineConfig({
network: {
proxy: "http://proxy.corp.example:3128",
noProxy: [".corp.example", "localhost"],
},
});Пишите записи NO_PROXY так, как их читает Bun. Домен с точкой в начале, .corp.example, покрывает свои поддомены — там, где пользователи curl часто пишут *.corp.example. Диапазоны CIDR вроде 10.0.0.0/8 не работают: перечислите хосты. ctxray doctor предупреждает об обеих формах. Ещё он предупреждает, когда задан только HTTP_PROXY: ctxray и HTTPS отправляет через него, а вот запущенные им MCP-серверы ходят мимо.
Через этот прокси идут запросы самого ctxray: установка харнессов, реестр, upstream модели. Запущенные им харнессы выходят в сеть только через прокси ctxray (Изоляция). MCP-серверы, запущенные за ctxray, получают ваши настоящие HTTPS_PROXY, HTTP_PROXY и NO_PROXY.
Прокси, который вскрывает TLS, требует ваш корневой сертификат. Дополнительные CA-файлы ctxray берёт из трёх мест:
| Где | Что |
|---|---|
network.ca в конфиге |
PEM-файлы, пути относительно конфига, который их называет |
NODE_EXTRA_CA_CERTS |
один PEM-файл, добавляется к файлам из конфига |
ca и cafile в .npmrc
|
для реестра (ниже) |
network.systemCa: true или NODE_USE_SYSTEM_CA=1 заставляют ctxray доверять ещё и системному хранилищу сертификатов. SSL_CERT_FILE не читается.
export default defineConfig({
network: {
ca: ["./certs/corp-root.pem"],
systemCa: true,
},
});MCP-серверы, запущенные за ctxray, получают те же сертификаты через NODE_EXTRA_CA_CERTS, а если файлов несколько, они сливаются в один PEM. ctxray doctor выдаёт ошибку на CA-файл, которого нет или в котором нет PEM-сертификата.
ctxray ставит харнессы из npm-пакетов. Реестр он выбирает так же, как npm, и побеждает первое совпадение:
-
network.registryв конфиге - реестр scope в
.npmrc, например@anthropic-ai:registry=… -
NPM_CONFIG_REGISTRY,npm_config_registryилиBUN_CONFIG_REGISTRY -
registry=в.npmrc https://registry.npmjs.org/
ctxray читает ваш пользовательский .npmrc ($NPM_CONFIG_USERCONFIG или ~/.npmrc), а потом .npmrc проекта рядом с ctxray.lock, который главнее. ${VAR} в значении берётся из окружения. Учётные данные уходят только в тот реестр, для которого предназначены, по самому длинному подходящему префиксу //host/path/::
registry=https://npm.corp.example/
//npm.corp.example/:_authToken=${NPM_TOKEN}
cafile=./certs/corp-root.pem_authToken уходит как bearer-токен, _auth или username с _password — как basic-аутентификация. ca и cafile ctxray читает сам, потому что за прокси Bun теряет сертификаты из .npmrc. Относительный cafile считается от своего .npmrc.
ctxray обращается к реестру, только когда закреплённого харнесса нет в кеше. Исключение — локальная сборка Cursor CLI: она приходит с downloads.cursor.com, а не из npm, поэтому зеркалируйте и этот хост или заносите сборку через harness pack.
offline: true в конфиге или CTXRAY_OFFLINE=1 оставляют всё на машине. ctxray не ставит харнессы из сети и подсказывает, как занести их иначе. Токены считаются только локально, с оценкой. ctxray test --backend real, ctxray gen-prompts и ctxray calibrate останавливаются, не начав, с кодом выхода 4.
Слоям L1–L5 сеть не нужна вовсе, поэтому офлайн они работают так же, как онлайн. L6 и L7 по-прежнему работают с --backend replay на записанных ответах или с mock. Корпоративному шлюзу внутри закрытой сети offline не нужен: укажите его в upstream, как показано в разделе LLM-шлюзы и ключи.
Занести харнессы в закрытую сеть можно тремя способами.
Архив. На машине с интернетом упакуйте сборки из ctxray.lock под все платформы ваших раннеров. Перенесите архив внутрь и установите из него. ctxray сверяет каждую сборку с integrity из ctxray.lock, как при скачивании:
# снаружи
ctxray harness pack --platform linux-x64-glibc,darwin-arm64 -o ctxray-harnesses.tar
# внутри
ctxray harness install --from ctxray-harnesses.tarОбщий кеш только для чтения. CTXRAY_CACHE_DIRS перечисляет несколько папок кеша через : (на Windows — ;). ctxray ищет во всех, а новые установки принимает первая доступная на запись. Положите один кеш на NFS или в образ раннера, и каждый job будет читать из него без копирования:
export CTXRAY_CACHE_DIRS="$HOME/.cache/ctxray:/mnt/nfs/ctxray"Слой только для чтения ctxray никогда не чистит, а ctxray doctor показывает каждый такой слой. Устройство кеша описано на странице Harnesses.
Образ раннера. harnesses.Dockerfile из релиза собирает образ с харнессами внутри (CI Integration).
Для самого ctxray каждый архив релиза — офлайн-комплект: исполняемый файл, JSON Schema, шаблон GitLab, harnesses.Dockerfile и плагин для Claude Code (Getting Started).
install.sh и install.ps1 скачивают из GitHub Releases. CTXRAY_DOWNLOAD_BASE направляет их на ваше зеркало, которое повторяет структуру GitHub:
<base>/latest/download/<asset>
<base>/download/v<version>/<asset>
curl -fsSL https://mirror.corp.example/ctxray/latest/download/install.sh \
| CTXRAY_DOWNLOAD_BASE=https://mirror.corp.example/ctxray shЗеркалируйте вместе с архивами и SHA256SUMS: скрипт сверяет с ним каждую загрузку. GitHub Action принимает ту же базу во входном параметре download-base:
- uses: MairwunNx/ctxray-action@v0
with:
download-base: https://mirror.corp.example/ctxraynpm-пакеты приходят через ваш npm-прокси, как любые другие: @mairwunnx/ctxray и пакет платформы, от которого он зависит, например @mairwunnx/ctxray-linux-x64. Образы с ghcr.io/mairwunnx/ctxray переносятся в ваш реестр контейнеров, а CTXRAY_IMAGE направляет на них шаблон GitLab.
extends строит конфиг проекта поверх других: путей или npm-пакетов из вашего реестра. Опубликуйте лимиты токенов, запрещённые MCP-серверы, шлюз и CA-файл один раз, в виде пакета:
// @acme/ctxray-config, index.ts
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
upstream: "https://llm-gateway.corp.example",
network: { ca: ["./corp-root.pem"] },
policies: [
{ id: "context-budget", maxTokens: { total: 25000 } },
{ id: "no-public-mcp", denyMcp: ["filesystem"] },
],
redact: { patterns: [/ACME-[0-9]{6}/] },
});// ctxray.config.ts проекта
import { defineConfig } from "@mairwunnx/ctxray";
export default defineConfig({
extends: "@acme/ctxray-config",
harnesses: { "claude-code": {}, codex: {} },
});ctxray находит пакет в node_modules проекта, поэтому поставьте его как dev-зависимость. Путь к CA в пакете остаётся относительным пакету. Проект может поправить унаследованную политику по её id, например её строгость, но убрать шаблоны редактирования не может. Правила слияния — на странице Configuration, проверки — на странице Policies.
ctxray никуда не отправляет данные о вас. Нет ни телеметрии, ни проверки обновлений, ни отчётов о сбоях. Он обращается только к настроенному вами реестру, когда нужно поставить харнесс, и к upstream модели — в прогонах, которые спрашивают настоящую модель.
Секреты и персональные данные скрываются до того, как что-то попадёт на диск. ctxray заменяет API-ключи, токены, приватные ключи, email, номера телефонов и карт метками вида ⟦redacted:anthropic-key⟧ по своим шаблонам и правилам gitleaks, плюс шаблонам, которые ваш конфиг добавляет в redact.patterns. Это касается вывода в консоль, каждого отчёта, трейсов, кассет, и логов MCP. Шаблоны перечислены на странице Reporters and Reports.
- Трейсы запросов харнесса лежат во временной папке системы, и ctxray удаляет их в конце прогона, если только не упал тест уровня L4 и выше.
- В настоящем прогоне запрос харнесса уходит в ваш upstream таким, каким его написал харнесс: это и есть обращение к модели.
Прогон с настоящей моделью перестаёт отправлять запросы, когда достигает бюджета. Тесты, которые начинаются после этого, пропускаются с причиной «бюджет исчерпан».
| Где | Что |
|---|---|
budget.usd в конфиге |
сколько долларов США может потратить прогон |
budget.tokens в конфиге |
сколько токенов может израсходовать прогон |
CTXRAY_BUDGET_USD |
доллары, поверх конфига |
--budget <usd> |
доллары, на один запуск ctxray test
|
Модели, которые ctxray запускает по умолчанию, у него уже с ценами. Для модели, которую шлюз отдаёт под другим именем, добавьте цену в prices в конфиге (Configuration). Модель, которую не удалось оценить, отчёт называет отдельно.
Начиная с L4, ctxray запускает настоящий харнесс. Он никогда не делает этого в вашем рабочем дереве или с вашей домашней папкой:
- Копия проекта. Харнесс работает на временной копии репозитория вместе с вашими незакоммиченными изменениями. Свои метки ctxray пишет только в копию.
-
Изолированный HOME.
HOME,TMPDIRи папкиXDG_*указывают в собственную папку прогона. Харнесс не видит~/.claude,~/.codex,~/.gemini,~/.config/opencode,~/.cursorи связку ключей macOS. Ваши собственные правила и MCP-серверы попадают в прогон только сuserScope: "inherit". -
Сторож исходящих соединений.
HTTPS_PROXY,HTTP_PROXYиALL_PROXYхарнесса указывают на сторожа, который отклоняет и запоминает каждое соединение. Трафик к модели может попасть только в прокси ctxray, а тест падает, если харнесс пытался выйти мимо него. - Телеметрия выключена. ctxray запускает каждый харнесс с выключенной телеметрией и проверкой обновлений — насколько харнесс это позволяет.
Захват шаг за шагом разобран на странице Harnesses, песочница — на странице CI Integration.
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие