어드바이저

어드바이저는 워커의 작업을 검토하고 조언을 반환하는 독립 전문가 모델입니다. 상담은 OpenCodex가 엔드투엔드로 소유합니다. 프록시가 워커 턴에 합성 advisor 도구를 주입하고, 정상적인 라우팅 권위를 통해 상담을 직접 실행하며, 조언을 재주입해 원래 워커가 계속 진행하게 합니다. 워커는 위임하지 않고, 아무것도 spawn하지 않으며, 제공자 자격 증명도 가지지 않습니다.

이는 서브에이전트 서피스(에이전트 구성 참조)와 다릅니다. 서브에이전트는 Codex 협업 도구를 통한 워커 주도 위임입니다. 어드바이저는 클라이언트에게 보이지 않는 프록시 측 사이드카입니다 — 아무것도 spawn하지 않는 워커도 조언을 받을 수 있습니다.

구성

대시보드 어드바이저 페이지에서 카탈로그 선택기로 전문가 모델을 선택하세요. 네이티브, 공급자, 계정 지정, 사용자 정의 및 콤보 선택자의 정확한 카탈로그 식별자를 저장합니다. 비활성 모델과 초기 선택 대기 모델은 새 선택에 표시하지 않습니다. 선택 가능한 목록에 없는 저장된 식별자는 경고와 함께 유지되며, 다른 모델을 선택하거나 지우기 전까지 변경되지 않습니다. 카탈로그 로드 실패 시 현재 선택을 보존하고 재시도를 제공합니다. 텍스트 조언을 반환할 수 있는 모델을 선택하세요. 카탈로그가 상담 호환성을 보장하지는 않습니다. CLI와 API는 라우터가 지원하는 모델 문자열을 계속 허용합니다.

{
  "advisor": {
    "enabled": true,
    "model": "gpt-6-astra",
    "effort": "max",
    "policy": "preflight",
    "contextSharingConsent": "v1"
  }
}

필드	타입	기본값	의미
`enabled?`	`boolean`	`false`	마스터 스위치. 비활성화 시 요청 경로에 어드바이저 동작이 전혀 없습니다.
`model?`	`string`	—	전문가 모델. 라우터가 허용하는 모든 모델 문자열: 네이티브 모델(`gpt-6-astra`), 명시적 `provider/model`(`anthropic/claude-sonnet-4-6`, `xai/grok-...`), 계정 한정 네이티브 모델. 크로스 프로바이더를 완전히 지원합니다.
`effort?`	`string`	`"max"`	어드바이저 호출의 추론 강도(`low`~`ultra`).
`policy?`	`"manual" \| "preflight" \| "adaptive"`	`"manual"`	상담 시점.
`maxConsultationsPerTask?`	`integer`	`3`	적응형 작업 상담 한도(1–3회 시도, 수동 호출 포함).
`timeoutMs?`	`number`	`120000`	루프백 상담 타임아웃.
`contextSharingConsent?`	`"v1"`	없음	설정된 어드바이저 프로바이더로 작업 맥락을 보내는 운영자 동의. 현재 값은 `"v1"`뿐입니다. 없거나, 오래되었거나, 다른 값이면 작업 내용을 보내지 않습니다. `enabled: true`만으로는 동의가 아닙니다.

현재 동의가 없으면 ocx advisor on은 프로바이더 간 전송을 켜지 않습니다. 고지를 출력하고 멈춥니다. ocx advisor on --ack-context-sharing와 ocx advisor consent가 v1을 기록합니다. ocx advisor consent --revoke는 동의를 지우고 전송을 즉시 멈춥니다. ocx advisor set은 동의를 부여하지 않습니다. 대시보드의 동의 확인란은 미리 선택되지 않습니다.

정책

manual — 워커가 합성 advisor 도구를 명시적으로 호출할 때만 상담합니다. 호출은 프록시가 가로채며 클라이언트에게 표시되지 않고 로컬 도구로 실행되지도 않습니다.
preflight — OpenCodex는 추가로 작업당 한 번의 상담을 자동으로 시도합니다. 실패한 상담은 조언으로 처리되지 않으며, 실패 원장 항목이 만료되면 다시 시도됩니다. 워커가 첫 방향 증거(최신 사용자 메시지 이후의 어시스턴트 도구 호출 또는 도구 결과)를 생성한 후, 워커가 도구를 호출하지 않아도 프록시는 전문가에게 상담하고 다음 턴 전에 조언을 주입합니다. 트리거는 결정론적이고 문서화된 근사이며, 의미 기반 “막힘” 감지기가 아닙니다.

동의

운영자가 맥락 공유 동의 v1을 기록하기 전에는 작업 맥락이 전송되지 않습니다. 동의는 버전을 가지므로, 이후 공개 범위가 넓어지면 옛 동의를 재사용하지 않고 v2를 요구할 수 있습니다. 런타임이 이를 강제합니다. 없거나 오래되면 어드바이저는 실행되지 않고(advisor_context_sharing_consent_required) 코딩 요청 자체는 계속됩니다. 워커, 어드바이저 모델, 작업 텍스트의 문자열은 동의를 부여할 수 없습니다.

어드바이저가 보는 것

상담이 보낼 수 있는 것:

최신 사용자 요청
파싱된 대화에 보이는 사용자, 어시스턴트, 개발자 텍스트
도구 호출과 인자
도구 결과
워커의 도구 목록과 설명
워커 식별과 설정된 어드바이저 모델
워커가 advisor()를 호출할 때의 선택적 초점 질문

설정된 어드바이저 프로바이더는 워커의 프로바이더와 다를 수 있습니다.

OpenCodex는 프로바이더 API 키, Authorization 헤더, OAuth 토큰, 백엔드 전용 설정 비밀, 프로세스 환경, 숨겨진 사고 과정을 그 프롬프트에 넣지 않습니다. 암호화된 프로바이더 사유 추론을 복호해 전달하지도 않습니다. 작업 내용의 비밀은 일반적으로 제거되지 않습니다. 작업에 붙여 넣은 키, 도구가 읽은 파일 속의 비밀, 도구나 로그가 출력한 토큰은 전송될 수 있습니다. OpenCodex는 범용 DLP를 실행하지 않습니다.

권한

수동 조언은 워커가 직접 호출한 advisor에 대한 도구 결과입니다. 결과는 JSON 객체입니다. advice는 어드바이저 모델의 텍스트입니다. status는 런타임이 씁니다.

자동 조언의 인용된 JSON은 별도의 user 역할 자문 메시지로 전달합니다. developer 메시지에는 고정된 런타임 지시만 남고, Advisor가 생성한 텍스트는 developer/system에 들어가지 않습니다. OpenAI Chat과 Anthropic 모두 가짜 도구 호출 없이 이를 지원합니다. JSON 인용은 구조 탈출과 필드 위조를 막지만 자연어 프롬프트 주입을 완전히 차단하지는 않습니다. 전용 프로토콜은 일반 사용자 입력과 조언을 더 명확히 구분할 수 있습니다. 요청당 상담은 최대 3회, 워커 이어가기는 최대 4회입니다. 상담 한도에 도달하면 advisor 도구를 제거하고 반복 호출에 한도 결과를 전달하는 마지막 이어가기를 한 번만 허용합니다. 다시 호출하면 추가 전송 없이 502 advisor_continuation_limit로 끝납니다. 빈 완료 재시도도 같은 한도를 공유합니다.

억제는 어드바이저 문자열을 읽지 않습니다. 자동 중복 제거는 서버가 소유한 원장뿐입니다. 전송 문장을 복사한 developer 메시지도 preflight를 억제하지 않습니다.

비용 및 회계

각 상담은 실제 추가 모델 호출입니다. 워커의 토큰 수에 합산되지 않고 어드바이저 모델의 사용량으로 기록되며, 각 상담은 트리거·시간·상태·사용량을 담은 [advisor] 로그 행을 기록합니다. 따라서 어드바이저 호출은 항상 로그에서 증명할 수 있습니다.

실패 동작

어드바이저는 fail-open입니다. 디스패치된 상담이 실패하면(모델 사용 불가, 설정 오류, 타임아웃) 워커는 짧고 오해의 소지가 없는 “어드바이저 사용 불가” 알림(preflight에서는 <opencodex_advisor_unavailable> 메시지, manual에서는 오류 도구 결과)을 받고 작업을 계속합니다. 아무것도 주입되지 않는 경우는 상담이 취소된 때뿐입니다. 상담이 시작되지 않는 구성(비활성, 모델 미설정, 또는 현재 맥락 공유 동의 없음)에서는 preflight 알림도 전송되지 않습니다. 현재 동의가 없는 수동 advisor() 호출은 consent-required 도구 결과를 반환하며 외부로 보내지 않습니다. 상담 실패가 코딩 요청을 실패하게 하지 않으며, 세션의 주 모델도 전환하지 않습니다.

PR1 제한

네이티브 OpenAI 패스스루 턴(ChatGPT 풀 워커)에는 합성 도구가 주입되지 않습니다. 어드바이저는 라우팅(번역) 제공자를 대상으로 합니다. preflight 상담은 run-turn 어댑터에 적용되지만 도구는 적용되지 않습니다.
의미 기반 막힘 감지, 완료 검토, 단계별 에스컬레이션, 다중 전문가 또는 투표는 제공하지 않습니다.
preflight 중복 제거 원장은 프로세스 내에 있습니다. 프록시 재시작 후 진행 중인 작업은 preflight 상담을 한 번 더 받을 수 있습니다.

증거 기반 적응형 상담과 활동 기록

adaptive는 초기 상담 외에 같은 작업 디렉터리의 같은 검증이 실패하고, 이후 파일 편집이 성공한 뒤 새 검증 실행도 실패했을 때 상담합니다. 검증 성공은 실패 상태를 지웁니다. 편집 전에 시작한 검증은 수정 후 재시도가 아닙니다. 초기 상담과 수정 실패 상담은 별도로 중복을 방지하며 자동 상담에는 안정적인 대화 식별자가 필요합니다. 짝지어진 도구 호출/결과와 명시적 종료 코드가 필요합니다. 복잡한 스크립트, 일괄 호출, shell 편집 및 모호한 출력은 트리거하지 않습니다.

ocx advisor set --policy adaptive --max-consultations 2로 설정합니다. 수동 및 자동 시도는 작업별 1–3회 예산을 공유하며 전송 전에 OPENCODEX_HOME/advisor-budget.sqlite에 예약합니다. 프록시 재시작이나 Worker 변경으로 초기화되지 않습니다. 작업 다이제스트, 횟수, 만료 시간만 보관하며 첫 시도 후 24시간에 만료됩니다(최대 512개 작업). 예산을 사용할 수 없어도 Worker는 계속합니다. 전송된 실패·취소 호출도 비용이 발생할 수 있으므로 예약을 돌려주지 않습니다. 안정적인 식별자가 없으면 요청별 수동 상담만 가능합니다.

Advisor 페이지와 ocx advisor activity --json(GET /api/advisor/activity)은 이 프로세스의 최근 24시간 상담 메타데이터를 최대 100개 표시합니다. 화면이 보일 때 5초마다 갱신합니다. 이유, 상태, 모델, 시간, 보고된 입력/출력 토큰, 요청 및 어댑터 매핑 추론값을 포함합니다. 작업 본문, 명령, 조언, 대화 식별자는 저장하지 않으며 재시작 시 사라집니다. 매핑은 전송 파라미터의 증거일 뿐 내부 추론을 보장하지 않습니다. 미보고 값은 알 수 없음으로 유지하며 정확한 비용이나 조언 채택을 추정하지 않습니다.