설치된 코딩 에이전트를 채팅 모델로 사용하기
이미 코딩 에이전트를 구독하고 있고 Libre WebUI를 실행하는 컴퓨터에서 로그인되어 있다면 별도의 API 키를 추가하는 대신 일반 채팅에서 사용할 수 있습니다. Libre WebUI는 에이전트의 명령줄 인터페이스를 감지하고 다른 모델처럼 모델 선택기에 표시합니다.
감지되는 항목
Libre WebUI는 모델 목록을 요청할 때마다 서버의 PATH에서 다음 명령을 찾습니다.
| 모델 | 명령 | 제공자 |
|---|---|---|
| Claude Code | claude | Anthropic |
| Codex | codex | OpenAI |
| OpenCode | opencode | SST |
| Pi | pi | Mario Zechner |
찾은 항목은 모델 선택기의 에이전트 그룹에 나타납니다. Libre WebUI가 대신 설치해 주는 항목은 없으며 설정 파일도 필요하지 않습니다. 서버 셸에서 명령이 실행되면 표시됩니다.
설정 → 채팅 → 기본값에서도 이 항목을 에이전트로 구분하며, 계정에서 사용할 수 있으면 Strands도 포함합니다. 플러그인 모델은 제공자 이름을 유지하고 Ollama 모델만 Ollama 레이블을 씁니다. Ollama를 꺼도 설정된 에이전트나 플러그인은 숨기지 않습니다. 모델 정보 카드에는 표시 이름과 제공자를 보여 주고, 크기·계열·형식은 카탈로그에 있을 때만 표시합니다.
CLI뿐 아니라 모델 선택하기
각 CLI는 에이전트 그룹에 여러 항목을 표시할 수 있습니다.
- Claude Code는 로그인된 기본 모델과 Sonnet, Opus, Haiku를 제공합니다.
명시적인 Sonnet 5.5(
claude-sonnet-5-5)와 Opus 5.5(claude-opus-5-5) 선택 항목도 제공합니다. Sonnet 5.5를 사용하려면 Claude Code 2.1.284 이상, Opus 5.5를 사용하려면 Claude Code 2.1.280 이상이 필요하며, 둘 다 로그인한 계정의 접근 권한이 필요합니다.claude update를 실행하여 CLI를 업데이트하세요. 기존 Sonnet 및 Opus 별칭은 계속 CLI의 현재 모델 매핑을 따릅니다. - Codex는 설정된 기본 모델과 문서화된 ChatGPT 로그인 제품군인 GPT-6 Astra, GPT-6.1 Sol (
gpt-6.1-sol), GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, Terra, Luna, GPT-5.5 및 GPT-5.3 Codex Spark를 제공합니다. 실제 제공 여부는 CLI의 로그인 상태와 계정의 모델 접근 권한에 따라 달라집니다. - Pi는 CLI 자체에 설정된 모델로 실행됩니다.
- OpenCode는 인증된 모든 제공자의 모델을 (
opencode models에서) 나열하며 항상 명시적으로 선택해야 합니다. CLI 수준 기본값은 Libre WebUI 호스트에서 접근할 수 없는 로컬 서버를 가리킬 수 있습니다.
내장 Strands 엔진도 계정에서 사용할 수 있으면 에이전트 그룹에 표시됩니다. Strands는 CLI가 아니라 백엔드 안에서 실행되며 Ollama 및 제공자 플러그인 모델을 구동합니다. 단독 Strands 항목(strands)은 기본 채팅 모델을 사용합니다. 나머지 항목(strands:<route>)은 **Strands · gpt-5.6-sol (Codex (ChatGPT))**처럼 사용 가능한 모델마다 하나씩 표시되며, 해당 대화의 모델과 제공자를 모두 고정하므로 장애 때 다른 제공자가 대신할 수 없습니다. 목록을 조회해도 엔진은 시작되지 않습니다.
같은 Strands 항목은 설정 → 채팅 → 기본값에서 자동 제목과 사고 요약용 작업 모델로도 사용할 수 있습니다. 현재 실행 중인 모델 사용은 대화에 저장된 Strands 선택을 사용합니다. 짧은 텍스트 요청은 기반 제공자 모델을 직접 호출하며, 에이전트 도구를 실행하거나 에이전트 세션을 만들지 않습니다. 다른 CLI 프로필에는 이 보조 요청용 Ollama, 플러그인 또는 Strands 작업 모델이 필요합니다.
Pi는 각 턴을 상태 없이(--no-session) 실행하며 로컬 도구를 비활성화하고 중립적인 시스템 프롬프트를 사용합니다. 따라서 서버 운영 체제 사용자의 개인 Pi 설정이 응답에 영향을 주거나 채팅에 접근하지 않습니다.
사용 방법
- 관리자로 로그인합니다.
- 채팅을 시작하고 모델 선택기를 엽니다.
- 에이전트 아래에서 항목을 선택합니다.
- 평소처럼 메시지를 보냅니다. 응답은 토큰 단위로 스트리밍됩니다.
대화는 다른 채팅과 동일하게 저장되므로 나갔다가 다시 돌아오고, 이름을 바꾸고, 명령 팔레트에서 검색할 수 있습니다. 각 턴은 최근 대화 기록을 에이전트에 보내고 답변을 스트리밍합니다.
사용할 수 있는 사람과 접근 가능한 범위
이 기능은 관리자 전용이며 그 이유가 중요합니다. 에이전트는 Work 컨테이너 안이 아니라 호스트에서 Libre WebUI 백엔드와 동일한 운영 체제 사용자로 실행됩니다. 따라서 해당 사용자의 에이전트 자격 증명과 에이전트가 일반적으로 갖는 모든 접근 권한을 상속합니다. 에이전트가 결정하면 서버의 파일을 읽고 명령을 실행할 수도 있습니다.
활성화는 에이전트에 컴퓨터 셸 접근을 허용하는 것과 같습니다. 따라서 기본적으로 비활성화되어 있으며 관리자가 설정 → 사용자 관리 → 접근 및 정책 → 에이전트 CLI 모델에서 켜야 합니다. 설정은 영구 저장되고 재시작 없이 즉시 적용됩니다.
이 컨트롤을 바꾸면 모델 목록이 즉시 갱신됩니다. 에이전트 범주에는 직접 CLI 항목이 있고 플러그인 모델에는 Codex (ChatGPT) 같은 제공자 API 통합이 있습니다. Strands도 같은 범주에 표시되지만 이 토글이 아니라 자체 Strands 엔진 접근 설정을 따르므로, 에이전트 CLI 모델이 꺼져 있어도 표시될 수 있습니다. Strands의 모델 검색은 설치된 CLI 에이전트 검색을 막을 수 없습니다.
기존 설치는 독립 CLI 설정을 저장하기 전까지 이전 에이전트 결정을 상속합니다.
런타임 토글과 관계없이 배포 수준에서 결정을 고정하려면 환경 변수를 어느 쪽으로든 설정하세요. 그러면 인터페이스의 토글도 잠깁니다.
AGENT_CLI_MODELS_ENABLED=false # or true
파일을 다룰 수 있으면서 샌드박스 안에 머무르는 모델이 필요하면 Work를 사용하세요. 도구를 지원하는 모델을 격리된 워크스페이스가 있는 엄격히 제한된 컨테이너에서 실행합니다.
사용량 추적
프로바이더 사용량(/usage)에서 상단 근처 에이전트를 찾으세요. Claude Code, Codex, OpenCode, Pi, Strands 활동이 별도 항목으로 표시되며 선택한 기간에 기록이 없으면 명확히 알려 줍니다.
LWUI를 통한 CLI 호출은 결과, 소요 시간, 보고된 토큰을 기록합니다. 호출당 사용량 이벤트 하나만 만들며 반복 스냅샷과 단계별 보고로 이벤트나 토큰이 중복되지 않습니다. 누락된 카운터는 미보고 상태로 유지합니다. 응답 중지는 취소로 기록하고 CLI가 일부 텍스트를 생성했어도 비정상 종료면 성공으로 처리하지 않습니다. LWUI 밖의 CLI 호출은 가져오지 않습니다.
Strands 호출은 Strands 에이전트에 귀속됩니다. 내역과 한도는 에이전트 사용량을 참조하세요.
설정
| 변수 | 기본값 | 용도 |
|---|---|---|
AGENT_CLI_MODELS_ENABLED | 설정 안 됨 | 기능을 true/false로 고정합니다. 설정하지 않으면 관리자 토글(기본값 꺼짐)을 따릅니다. |
AGENT_CLI_TIMEOUT_MS | 600000 | 에이전트의 한 턴이 종료되기 전까지 실행할 수 있는 시간 |
문제 해결
에이전트 그룹이 없음. 설정 → 사용자 관리 → 접근 및 정책 → 에이전트 CLI 모델에서 기능이 켜져 있고(기본은 꺼짐) 관리자로 로그인했는지 확인하세요. 명령은 대화형 셸뿐 아니라 백엔드 프로세스의 PATH에 있어야 합니다. 서비스 관리자, Docker 컨테이너, 데스크톱 런처의 PATH는 로그인 터미널보다 좁은 경우가 많습니다.
응답이 즉시 실패합니다. 서버 사용자로 동일한 명령을 직접 실행하세요(claude -p "hello" 또는 codex exec "hello"). 대부분은 에이전트 로그인이 만료되었거나 기본 구독의 사용량 제한에 도달해서 발생합니다. 특히 OpenCode는 만료된 제공자 로그인을 자체 로그에만 보고하므로 서버 사용자로 opencode auth login을 다시 실행하세요.
응답이 도중에 멈춥니다. 긴 턴이 AGENT_CLI_TIMEOUT_MS에 도달했을 수 있습니다. 값을 늘리거나 요청을 더 작은 단계로 나누세요.