Skip to content

Harnesses RU

Pavel Erokhin edited this page Nov 21, 2026 · 9 revisions

English version

ИИ-харнесс — программа, которая превращает модель в агента: Claude Code, Codex, Gemini CLI, OpenCode, Cursor. Каждый читает свои файлы, в своём порядке и со своими особенностями. Здесь описано, что ctxray знает о каждом харнессе, как он их запускает и как закрепляет версии, чтобы CI тестировал те же сборки, что и вы.

Матрица поддержки

ctxray знает пять id харнессов, других нет. Неизвестный id падает с ошибкой «Неизвестный ИИ-харнесс», а своего добавить нельзя.

L1–L3 работают для всех харнессов. L4–L7 запускают харнесс, поэтому работают для Claude Code, Codex, Gemini CLI и OpenCode, а для Cursor CLI — экспериментально.

id Название Режимы Возможности Модель по умолчанию Подсчёт токенов
claude-code Claude Code static, capture, observe skills, pathRules, mcp, hooks, headless, proxyable claude-sonnet-5-5 o200k с измеренными коэффициентами Claude: local:o200k_base+calibrated:claude-sonnet-5-5
codex Codex static, capture skills, mcp, hooks, headless, proxyable gpt-5.5 local:o200k_base
gemini-cli Gemini CLI static, capture skills, pathRules, mcp, hooks, headless, proxyable gemini-2.5-flash словарь Gemma, local:gemma4, o200k, если он не загрузился
opencode OpenCode static, capture skills, pathRules, mcp, hooks, headless, proxyable claude-sonnet-5-5 local:o200k_base
cursor-cli Cursor CLI static, capture (экспериментально) skills, pathRules, intentRules, mcp, hooks, headless claude-sonnet-5-5 local:o200k_base

Режимы подробно описаны на странице Capture Modes. Коротко: static читает файлы, capture запускает харнесс через прокси ctxray, а observe показывает текущую сессию Claude Code через плагин ctxray.

Тест может перечислить возможности, которые ему нужны, в requires (см. Writing Tests). Харнесс без такой возможности не валит тест, а помечает его skipped: unsupported:

Возможность Что значит
skills скиллы перечислены по описанию и загружаются по запросу
pathRules правила или вложенные файлы контекста загружаются, когда агент работает с подходящими файлами
intentRules правила (не скиллы), которые модель выбирает по описанию
mcp MCP-серверы и их инструменты
hooks hooks жизненного цикла, через которые ctxray может наблюдать
headless работает без интерфейса, поэтому ctxray может его запустить
proxyable отправляет запросы к модели на base URL, который задаёт ctxray

Каждое число токенов, посчитанное на вашей машине, — оценка, и рядом с ним стоит ≈. Точные числа даёт эндпоинт подсчёта у провайдера, см. Configuration (exactTokens).

Как ctxray читает проект

Несколько правил общие для всех харнессов, поэтому разделы ниже их не повторяют.

  • Какие файлы есть. ctxray спрашивает git: git ls-files --cached --others --exclude-standard, без удалённых файлов. Файл, который скрывает .gitignore, не считается — как он не дошёл бы и до коллеги. Вне git ctxray обходит папку и пропускает .git/ и node_modules/. В обоих случаях он не берёт свои папки в корне проекта, .ctxray/ и .ctxray-cache/: их не читает ни один харнесс.
  • Цепочка. Папки от корня проекта до папки, в которой стартует агент (--cwd), образуют цепочку. Файлы цепочки обычно загружаются при запуске.
  • Ниже стартовой папки. Когда агент работает с файлом глубже (--files), папки между стартовой и этим файлом могут добавить свои файлы контекста.
  • Активация. Каждое правило объясняет, почему загрузилось: always (в каждой сессии своей папки), path (когда агент работает с подходящим файлом), intent (модель выбирает его по описанию) или manual (только если вы его назвали). Причина рядом — одна из cwd, always, nested:<file>, glob:<glob>, import:<path>, description, config.
  • Чего не знает static. Системный промпт, встроенные инструменты и схемы инструментов MCP живут внутри харнесса. ctxray inspect показывает MCP-серверы по имени, а для остального пишет «после запуска». Их заполняет capture.

Какие файлы читает каждый харнесс

У каждого харнесса свой список файлов. Порядок и подробности — в разделах ниже.

Таблица файлов инструкций, правил, скиллов и MCP и того, кто из Claude Code, Codex, Gemini CLI, OpenCode и Cursor читает каждый.

Claude Code

ctxray повторяет поведение Claude Code 2.1.

Файлы и порядок. Claude Code читает CLAUDE.md, CLAUDE.local.md и правила из .claude/rules/**/*.md. В каждой папке цепочки порядок такой: CLAUDE.md, затем правила без paths, затем CLAUDE.local.md. CLAUDE.md внутри .claude/ относится к папке, в которой лежит .claude/. CLAUDE.local.md ctxray ищет в каждой папке, даже если git его игнорирует: для этого такой файл и нужен. Файл больше 4 МиБ — ошибка.

AGENTS.md — только без CLAUDE.md. Claude Code читает AGENTS.md, только если в цепочке нет ни одного CLAUDE.md, и в папке — только если в ней нет CLAUDE.md или CLAUDE.local.md. AGENTS.md, который заслонил CLAUDE.md и который никто не импортирует, попадает в список проигнорированных. Если нужны оба, импортируйте его из CLAUDE.md строкой @AGENTS.md.

Импорты на четыре шага. @path подтягивает файл относительно импортирующего, а импортированный файл может импортировать дальше, до 4 шагов. Пути, которые начинаются с ~ или / или выходят за проект, не загружаются. Импорты раскрываются только в файлах стартовой папки и ниже: CLAUDE.md выше стартовой папки загружается без своих импортов. ctxray проверил это на Claude Code 2.1.311.

Активация.

  • Файлы цепочки загружаются как always, причина cwd.
  • Папка ниже стартовой, в которой лежит рабочий файл агента, добавляет свои файлы как path, причина nested:<file>.
  • Правило с paths: во frontmatter загружается как path, причина glob:<glob>, когда рабочий файл подходит. Глобы считаются от папки правила.
  • Во frontmatter правила Claude Code читает только paths. Любое другое поле, например globs от Cursor, даёт предупреждение lint.ruleField.

Скиллы. .claude/skills/<folder>/SKILL.md в любой папке, до которой агент может дойти. Имя скилла — это папка: другое name во frontmatter даёт предупреждение. Описание — это description (или первая строка текста) плюс when_to_use, обрезанные до 1536 символов. disable-model-invocation: true убирает скилл из списка. paths: показывает его, только когда рабочий файл подходит. Claude Code смотрит ровно на одну папку вглубь: .claude/skills/payments/refunds/SKILL.md не загрузится никогда. Таб во frontmatter заставляет его пропустить скилл.

Команды. .claude/commands/**/<name>.md. Скилл с тем же именем побеждает команду.

MCP. mcpServers в .mcp.json. Каждому серверу нужен command или url. disabledMcpjsonServers в .claude/settings.json или .claude/settings.local.json выключает серверы.

Capture. ctxray запускает:

claude -p <prompt> --output-format stream-json --verbose --model <model> --permission-mode bypassPermissions

CLAUDE_CONFIG_DIR лежит в собственном home прогона, ANTHROPIC_BASE_URL указывает на прокси ctxray, ANTHROPIC_API_KEY — пустышка, а телеметрия, отчёты об ошибках, автообновление и лишний трафик выключены. Под root Claude Code отказывается от bypassPermissions, поэтому только тогда ctxray ставит IS_SANDBOX=1. .mcp.json проекта в копии переписывается так, чтобы каждый сервер работал за ctxray.

Рецепт установки. npm-пакет @anthropic-ai/claude-code, dist-tag по умолчанию stable. Нативная сборка берётся из @anthropic-ai/claude-code-<os>-<arch>[-musl]@<version>, исполняемый файл claude (claude.exe на Windows).

Codex

ctxray повторяет поведение Codex 0.169.

Файлы и порядок. В каждой папке цепочки Codex берёт первый непустой файл из AGENTS.override.md, AGENTS.md и затем имён из project_doc_fallback_filenames в .codex/config.toml. Остальные файлы этой папки заслонены, а пустой файл даёт предупреждение.

Без правил по путям. Codex фиксирует цепочку от корня до стартовой папки в начале сессии. Чтение файла глубже ничего не загружает, поэтому каждое правило Codex — always, причина cwd. Тест, которому нужен pathRules, на Codex пропускается.

Бюджет 32 КиБ. Codex останавливается на project_doc_max_bytes, по умолчанию 32 КиБ (32768 байт). Файл, который переходит границу, обрезается, а файлы после него отбрасываются. ctxray предупреждает об обоих случаях, так что вы видите, какие инструкции до модели не доходят.

Скиллы. .agents/skills/<folder>/SKILL.md в цепочке, от стартовой папки до корня, плюс .codex/skills/<folder>/SKILL.md в корне, в том числе во вложенных папках, как .agents/skills/payments/refunds/SKILL.md. name и description обязательны, скилл без них — ошибка. Ещё Codex пропускает SKILL.md, который начинается с BOM или содержит таб во frontmatter. Запись [[skills.config]] с enabled = false выключает скилл по name или по абсолютному path. Побеждает последнее совпадение.

Команды. Проектных команд у Codex нет.

MCP. [mcp_servers.<name>] в .codex/config.toml. enabled = false выключает сервер. О сломанном TOML ctxray сообщает.

Capture. ctxray запускает:

codex exec --json -s read-only -m <model> --skip-git-repo-check <prompt>

CODEX_HOME лежит в home прогона. ctxray пишет туда config.toml со своим провайдером модели (base_url ведёт на прокси, Responses API, без повторов), выключает аналитику, отзывы, историю и проверку обновлений и помечает копию как доверенную. MCP-серверы уходят за ctxray через переопределения -c mcp_servers.<name>.…. Сервер, в имени которого есть точка, так переопределить нельзя. Codex сам запускает себя в песочнице, а macOS не пускает песочницу в песочницу, поэтому ctxray запускает Codex без своей.

Рецепт установки. npm-пакет @openai/codex, dist-tag latest. Каждая сборка — пререлиз того же пакета, @openai/codex@<version>-<os>-<arch>. Сборки для Linux — статические исполняемые файлы на musl, поэтому машины с glibc и с musl используют одну и ту же.

Gemini CLI

ctxray повторяет поведение Gemini CLI 0.68.

Файлы и порядок. Gemini CLI читает GEMINI.md и имена, которые добавляет context.fileName в .gemini/settings.json (строка или список). Файл с именем AGENTS.md считается файлом AGENTS. Файлы контекста от корня до стартовой папки загружаются как always, отсортированные по пути. Когда агент трогает файл глубже, файлы контекста между стартовой папкой и этим файлом добавляются как path, причина nested:<file>. Пустые файлы пропускаются с предупреждением.

Импорты. @path идёт до 5 шагов. Импортированный файл наследует активацию файла, который его импортирует, причина import:<path>.

Настройки только из стартовой папки. Gemini CLI читает .gemini/settings.json только в той папке, где стартует. Со скиллами и командами так же: считаются только .gemini/ и .agents/ самой стартовой папки. .gemini/settings.json в родительской или вложенной папке важен только для сессии, которая стартует там, поэтому проверяйте каждую стартовую папку, которой пользуетесь, через --cwd.

Скиллы. .gemini/skills/<folder>/SKILL.md и .agents/skills/<folder>/SKILL.md. Gemini CLI смотрит ровно на одну папку вглубь. name и ключ description обязательны: скилл без них Gemini CLI молча отбрасывает, а ctxray предупреждает. С пустым description: скилл всё же попадает в список, но выбрать его модели не по чему. В name символы : \ / < > * ? " | заменяются на -.

Команды. .gemini/commands/**/*.toml с prompt и description. git/commit.toml превращается в /git:commit. Gemini CLI раскрывает команды сам и модели их не показывает.

MCP. mcpServers в .gemini/settings.json стартовой папки, транспорт command, url или httpUrl. mcp.allowed оставляет только названные серверы, mcp.excluded убирает серверы.

Capture. ctxray запускает:

gemini -p <prompt> -m <model> -o stream-json --approval-mode yolo

Сборка из кеша ctxray — это bundle/gemini.js, поэтому ctxray запускает её через node. yolo заставляет Gemini CLI показать модели все инструменты. GOOGLE_GEMINI_BASE_URL указывает на прокси, GEMINI_CLI_HOME — на home прогона, а пути к системным настройкам — на несуществующие файлы, так что настройки вашей машины не попадают в прогон. Файл настроек в home прогона выбирает авторизацию по API-ключу и выключает статистику, телеметрию и автообновление. Gemini CLI нужен node в PATH: без него capture падает, а ctxray doctor об этом говорит.

Рецепт установки. npm-пакет @google/gemini-cli, dist-tag latest. Это один бандл для всех платформ, bundle/gemini.js, который запускает Node.

OpenCode

ctxray повторяет поведение OpenCode 1.19.

Побеждает первое имя. OpenCode знает три имени файлов контекста, в таком порядке: AGENTS.md, CLAUDE.md, CONTEXT.md. При запуске он выбирает первое имя, которое встречается где-нибудь между стартовой папкой и корнем, и загружает все файлы с этим именем по пути, always, причина cwd. Файл с меньшим приоритетом рядом с файлом с большим не загружается никогда. Так что одного AGENTS.md глубоко в дереве хватает, чтобы все CLAUDE.md над ним стали невидимыми.

Инструкции из конфига. instructions в opencode.json, opencode.jsonc или .opencode/opencode.json(c) по цепочке добавляет файлы по пути или глобу, always, причина config. URL, пути с ~/ и абсолютные пути не загружаются.

Ниже стартовой папки. Каждая папка между стартовой и тронутым файлом добавляет свой первый файл контекста как path.

Скиллы. .opencode/skill/, .opencode/skills/, .claude/skills/ и .agents/skills/, каждый как <folder>/SKILL.md, в том числе во вложенных папках, от стартовой папки до корня. Более глубокий скилл скрывает одноимённый скилл выше. name и строка description обязательны: description: "" проходит, пустой description: — нет.

Команды. .opencode/command/ или .opencode/commands/ (**/*.md) и записи command в конфиге (template, description). OpenCode раскрывает их сам и модели не показывает.

MCP. mcp в конфиге: у локального сервера command — список или строка, у удалённого — url. enabled: false выключает сервер. Конфиги сливаются от корня к стартовой папке, побеждает более глубокий.

Capture. ctxray запускает opencode run --format json -m <provider>/<model> и передаёт промпт через stdin. Конфиг приходит через OPENCODE_CONFIG_CONTENT, с выключенными автообновлением, загрузкой списка моделей и скачиванием LSP. Если provider харнесса в вашем конфиге — anthropic или openai, OpenCode говорит с этим провайдером через ctxray. Иначе ctxray добавляет OpenAI-совместимый провайдер с именем ctxray, который говорит на Chat Completions. Каждый конфиг OpenCode по цепочке в копии направляет свои MCP-серверы через ctxray.

Рецепт установки. npm-пакет opencode-ai, dist-tag latest. Нативная сборка — opencode-<os>-<arch>[-musl]@<version>, где вместо win32 стоит windows, исполняемый файл bin/opencode. Установочный скрипт обёртки не запускается: он писал бы в ваш настоящий home.

Cursor CLI

ctxray повторяет поведение локальной сборки Cursor CLI 2026.11.

Файлы. AGENTS.md, CLAUDE.md и CLAUDE.local.md в любой папке, правила в .cursor/rules/**/*.mdc (и .MDC, но никогда .md) и старый .cursorrules в корне, который действует всегда.

Frontmatter .mdc построчно. Cursor разбирает frontmatter правила не как YAML, а построчно, поэтому globs: *.ts в Cursor работает, хотя YAML такое отвергает. ctxray читает так же. true и false становятся булевыми значениями, кавычки снимаются, а ключ без значения собирает строки - item под собой в список.

Активация проверяется в таком порядке:

Frontmatter Активация
alwaysApply: true (настоящее булево значение, не "true") always
непустой globs path, причина glob:<glob>, когда рабочий файл подходит
description intent: модель выбирает правило по описанию, поэтому в токены идёт только описание
ничего из этого manual: только когда вы его упомянули

AGENTS.md, CLAUDE.md, CLAUDE.local.md и правила с alwaysApply загружаются от корня до стартовой папки как always. Глубже те же файлы загружаются как path в каждой папке между стартовой и файлом, который прочитал агент.

В трёх вещах Cursor ведёт себя иначе, чем остальные харнессы, и ctxray это повторяет:

  • Glob без слэша считается от папки правила. globs: docker-compose*.yml в корневом .cursor/rules подходит к docker-compose.yml, но не к sub/docker-compose.dev.yml. Для любой глубины пишите **/docker-compose*.yml. Claude Code тот же шаблон применяет на любой глубине.
  • Правила с описанием — со всего рабочего пространства. Правило только с description предлагается модели на старте, где бы оно ни лежало, включая sub/deep/.cursor/rules/.
  • CLAUDE.md-ссылка загружается один раз. Если CLAUDE.md и AGENTS.md в одной папке — один и тот же файл через символическую ссылку, Cursor загружает его один раз, как AGENTS.md. Два отдельных файла с одинаковым текстом загружаются оба.

Скиллы. SKILL.md в .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/ или .grok/skills/. Вложенные папки тоже считаются. Имя — name во frontmatter или папка, а скилл без description пропускается. paths и disable-model-invocation: true работают как в Claude Code. При запуске перечислены скиллы стартовой папки, а скиллы более глубокой папки добавляются, когда агент читает в ней файл.

Команды. .cursor/commands/**/*.md. Они принадлежат редактору Cursor, поэтому в headless-прогоне до модели ничего не доходит.

MCP. mcpServers в .cursor/mcp.json в любой папке цепочки.

Capture — экспериментальный. Base URL принимает только скрытая локальная сборка Cursor CLI, cursor-agent-local. ctxray запускает её так:

cursor-agent-local --authless --base-url <proxy>/v1 -p --output-format stream-json --trust --approve-mcps --force --disable-auto-update --model <model> <prompt>

Эта сборка не задокументирована, поэтому capture выключен, пока вы его явно не включите:

export default defineConfig({
  harnesses: { "cursor-cli": { experimental: true } },
});

Cursor CLI говорит на Chat Completions, где нет эндпоинта подсчёта токенов, поэтому его числа остаются оценками.

Рецепт установки. cursor-agent-local нет в npm. ctxray берёт текущую версию из https://cursor.com/install и скачивает https://downloads.cursor.com/lab/<version>/<os>/<arch>/agent-cli-local-package.tar.gz, сверяя его с файлом .sha256 рядом. Сборки есть для macOS и Linux с glibc, x64 и arm64. Редактор Cursor ctxray не ставит.

Как проходит capture

L4 и выше запускают харнесс (см. The Loadout Stack). ctxray никогда не запускает его в вашем рабочем дереве или с вашим home:

ctxray копирует проект, ставит в каждый файл метку и даёт каждой сессии свою папку. Харнесс работает в песочнице: запросы к модели идут в прокси ctxray, MCP-серверы стоят за прослойкой ctxray, а любое другое соединение упирается в сторожа. Трейс без секретов режется на сегменты, из которых получается Loadout для вашего теста.

  1. ctxray копирует проект во временную папку, вместе с незакоммиченными изменениями и игнорируемыми файлами инструкций вроде CLAUDE.local.md. В конец каждого файла инструкций, скилла и команды в копии он дописывает канарейку ⟦ctx:<path>⟧, чтобы понять, какой файл дошёл до модели.
  2. Каждая сессия получает свою папку с work, home, tmp, bin и logs. Харнесс видит там HOME, TMPDIR и папки XDG_*, а также TERM=dumb, LANG=en_US.UTF-8 и TZ=UTC. Заглушка security в bin не пускает его к связке ключей macOS.
  3. В HTTPS_PROXY, HTTP_PROXY и ALL_PROXY стоит страж исходящих соединений. Он отклоняет и записывает каждое соединение, так что трафик модели может дойти только до прокси ctxray.
  4. На macOS sandbox-exec запрещает запись за пределами папки прогона. На других системах песочницы нет: запускайте L4 и выше в контейнере, как в CI.
  5. MCP-серверы на stdio оборачиваются в shim ctxray, HTTP-серверы идут через прокси. Оба пути пишут лог того, что ответил сервер, и по нему ctxray считает схему каждого инструмента.

Ваши пользовательские файлы

По умолчанию прогон не видит ваших пользовательских файлов. Поставьте харнессу userScope: "inherit" (Configuration), и ctxray скопирует их в home прогона. Он копирует файлы, а не ссылается на них, и никогда не копирует файлы настроек: такой файл мог бы увести харнесс мимо ctxray. Ваши MCP-серверы тоже всегда работают за ctxray.

Харнесс Что попадает в прогон
Claude Code CLAUDE.md, rules, skills, agents, commands, output-styles из $CLAUDE_CONFIG_DIR или ~/.claude. MCP-серверы из ~/.claude.json: и общие, и серверы этого проекта. Из вашего settings.json — только hooks
Codex AGENTS.md, AGENTS.override.md, skills, prompts, hooks.json из $CODEX_HOME или ~/.codex, плюс ~/.agents/skills. MCP-серверы из config.toml, причём одноимённый сервер проекта побеждает
Gemini CLI GEMINI.md, skills, commands, agents из ~/.gemini (или $GEMINI_CLI_HOME/.gemini), плюс ~/.agents/skills. mcpServers и hooks из вашего settings.json. Расширения не попадают
OpenCode AGENTS.md, скиллы, команды и агенты из ~/.config/opencode (или $XDG_CONFIG_HOME/opencode), плюс ~/.claude/CLAUDE.md, ~/.claude/skills, ~/.agents/skills. MCP-серверы из вашего конфига
Cursor CLI ~/.cursor/skills, ~/.cursor/commands, ~/.cursor/hooks.json, ~/.agents/skills, ~/.claude/skills, ~/.codex/skills и MCP-серверы из ~/.cursor/mcp.json. Пользовательские правила Cursor хранит в аккаунте, так что копировать нечего

Установка харнессов

Харнесс в PATH — той версии, которую вы поставили последней. Для беглого взгляда это нормально, для CI — нет. ctxray закрепляет точные сборки в ctxray.lock, ставит их в свой кеш и запускает оттуда.

ctxray.lock

Lockfile лежит рядом с конфигом или в текущей папке, если конфига нет. Запуск из подпапки находит конфиг, а с ним и тот же lockfile. Это JSON, харнессы отсортированы по id. Пишет его только ctxray harness, а вы его коммитите.

{
  "lockfileVersion": 1,
  "harnesses": {
    "claude-code": {
      "source": "registry",
      "range": "2.1.325",                // что вы попросили: диапазон, версию или тег
      "version": "2.1.325",              // во что это разрешилось
      "platforms": {                     // по сборке на платформу, сразу все
        "darwin-arm64": {
          "package": "@anthropic-ai/claude-code-darwin-arm64@2.1.325",
          "integrity": "sha512-Ds1f1B+qy2BWDI+VnmDHwkNyTbXCwFrBtrinPD95RBmUubFJu9nCzMgn+wrg5VwwF6vtkkzGexogneZIYZKb6A=="
        }
        // … linux-x64-glibc, linux-x64-musl, win32-x64 и остальные
      }
    },
    "codex": {
      "source": "system",                // запускать тот, что в PATH, и записать его версию
      "version": "0.169.0"
    }
  }
}

Один lockfile подходит и для Mac, и для Linux-раннера, и для Alpine, потому что harness add разрешает все платформы сразу. Каждую загрузку ctxray сверяет с integrity: sha512-… из npm, sha256-… для загрузки Cursor.

Закрепить и поставить

ctxray harness add claude-code codex@0.169.x   # разрешить версии и записать ctxray.lock
ctxray harness install                         # поставить закреплённое, как bun install
ctxray harness list                            # lock, конфиг и эта машина рядом
  • harness add <id>[@range] берёт диапазон из аргумента, затем из version харнесса в конфиге, затем dist-tag рецепта. Он находит точную версию и integrity для каждой платформы.
  • harness install ставит на эту машину все закреплённые харнессы. Для каждого итог — cache (уже есть), install (скачан сейчас), path (системный харнесс) или missing.
  • harness list показывает, что закреплено и есть ли это на машине.
  • harness pack собирает закреплённые сборки в один архив, по умолчанию ctxray-harnesses.tar, для этой платформы или тех, что вы назовёте. harness install --from <archive> ставит из него без registry — так харнессы попадают на машину без сети (Enterprise).
  • harness upgrade <ids> обновляет харнесс до самой новой версии, которую разрешает диапазон, снимает стартовый контекст старой и новой сборки на mock-модели и показывает, как изменился loadout. --dry-run оставляет ctxray.lock как есть.

Все параметры — на странице Commands.

source: "system"

Некоторые команды ставят харнессы своими средствами. Укажите source: "system", и ctxray запустит харнесс, который найдёт в PATH:

export default defineConfig({
  harnesses: { "claude-code": { source: "system" } },
});

ctxray harness add claude-code тогда записывает версию из PATH (её узнают с временным home). Системный харнесс ctxray не обновляет: обновите его в PATH и снова запустите harness add. Харнесс, который не закреплён и не system, тоже берётся из PATH.

--frozen в CI

Lockfile, который расходится с конфигом, — проблема: харнесса нет в lock, у system-харнесса нет версии, сменился source или version в конфиге не совпадает с закреплённым диапазоном. Локально ctxray только упоминает об этом. С --frozen ctxray test валит тесты, которым нужен этот харнесс, а ctxray harness install ничего не скачивает и выходит с кодом 4. В CI и с --ci --frozen включается сам, для обеих команд.

--no-install

ctxray test ставит закреплённый харнесс, которого нет в кеше, при первом обращении. ctxray test --no-install в этом случае падает — это подходит раннеру, которому нельзя ходить в registry.

Кеш

Сборки харнессов лежат в одном кеше на машину, общем для всех проектов.

Система Папка по умолчанию
macOS ~/Library/Caches/ctxray
Windows %LOCALAPPDATA%\ctxray\Cache
Linux $XDG_CACHE_HOME/ctxray или ~/.cache/ctxray
  • CTXRAY_CACHE_DIR заменяет папку по умолчанию. Относительный путь отсчитывается от папки, в которой запущен ctxray, как и относительные записи CTXRAY_CACHE_DIRS.
  • CTXRAY_CACHE_DIRS перечисляет несколько папок через : (; на Windows). ctxray ищет во всех по порядку, а новые установки идут в первую, куда можно писать. Остальные — слои только для чтения, например кеш на NFS или вшитый в образ раннера, и их ctxray никогда не чистит.

Внутри каждая сборка лежит в harnesses/<harness>/<version>+<platform>+<sha8>/. Два процесса, которые ставят одновременно, ждут друг друга, а сборка появляется только после проверки integrity.

ctxray cache dir                    # папка для записи, для шага кеширования в CI
ctxray cache ls                     # сборки во всех слоях
ctxray cache prune --older-than 14  # сборки, которыми не пользовались 14 дней
ctxray cache prune --all            # все сборки, которых нет в ctxray.lock
ctxray cache clear --yes            # все сборки, в том числе закреплённые

cache prune оставляет сборки, закреплённые в вашем ctxray.lock. Шаг кеширования с cache dir показан на странице CI Integration.

Ключи платформ

Lockfile и кеш называют платформы такими ключами:

Ключ Машина
darwin-arm64 macOS на Apple silicon
darwin-x64 macOS на Intel
linux-x64-glibc Linux x64 с glibc
linux-x64-musl Linux x64 с musl, например Alpine
linux-arm64-glibc Linux arm64 с glibc
linux-arm64-musl Linux arm64 с musl
win32-x64 Windows x64
win32-arm64 Windows arm64

musl ctxray узнаёт по загрузчику /lib/ld-musl-*. harness pack --platform принимает эти ключи через запятую или all.

Registry, прокси и авторизация через .npmrc описаны на странице Enterprise.

Clone this wiki locally