Octop 자체 호스팅: 다중 사용자 AI 어시스턴트 구축 가이드

Octop이란 무엇이며, 왜 직접 호스팅해야 하는가

Octop은 가정이나 소규모 팀을 위한 자체 호스팅 AI 어시스턴트입니다. 일반적인 채팅 프런트엔드가 아닌 Octop을 직접 호스팅하는 이유는 사용자 간의 격리를 보장하기 때문입니다. Open WebUI는 모델 앞단에 브라우저 인터페이스를 제공하는 수준에 그칩니다. 반면 Octop은 관리자 역할이 포함된 계정 시스템, 사용자별 개인 작업 공간 및 자격 증명 세트, 그리고 작업마다 전환할 수 있는 전문 에이전트 라이브러리를 추가합니다. 바로 이 차이점 덕분에 한 대의 VPS로 한 명이 아닌 다섯 명의 사용자를 지원할 수 있습니다.

이 프로젝트는 github.com/TencentCloud/Octop에서 확인할 수 있습니다. 웹 대시보드, 명령줄 인터페이스, 채팅 채널(Feishu, DingTalk, QQ, Discord, WeCom) 및 예약 작업을 하나의 프로세스로 처리하며, 이 모든 데이터는 ~/.octop/ 아래의 단일 SQLite 데이터베이스에 저장됩니다. 아래의 모든 내용은 2026년 8월 5일에 릴리스된 v0.9.19 태그를 기준으로 작성되었습니다. 플랫폼 선택을 고민 중이라면 VPS에서 실행 가능한 Open WebUI 대안 비교 문서를 통해 더 넓은 범위를 살펴보시기 바랍니다.

설치를 시작하기 전에 한 가지 명확히 할 점이 있습니다. Octop은 2026년 8월 기준 약 900개의 스타를 기록 중인 벤더의 GitHub 조직에서 배포하는 1.0 버전 이전의 소프트웨어입니다. 버전 번호에서 알 수 있듯이 빠르게 변화하고 있으며, 이 문서의 어떤 내용도 안정적인 업그레이드 경로를 보장하지 않습니다. 특정 태그를 고정하고, 변경 로그를 읽고, 항상 백업을 유지하십시오.

시작하기 전에 필요한 것

• Docker Engine과 Compose 플러그인이 설치된 Ubuntu 24.04 VPS. Compose가 처음이라면 VPS를 위한 Docker Compose 기초부터 확인하십시오.
• git. 이미지를 가져오는 대신 릴리스 태그를 체크아웃할 예정이기 때문입니다.
• VPS를 가리키는 도메인 이름. 앞단에 TLS(전송 계층 보안)를 적용해야 하기 때문입니다.
• OpenAI API와 호환되는 모델 백엔드. 로컬 Ollama, 자체 호스팅 게이트웨이 또는 유료 키를 사용할 수 있습니다.

Octop 자체는 가볍습니다. Python 프로세스와 SQLite 파일로 구성됩니다. 리소스 사용량은 모델 백엔드에서 발생하므로, 같은 서버에서 모델을 실행할 계획이라면 모델 사양에 맞춰 서버 크기를 결정하십시오.

curl 설치 프로그램을 권장하지 않는 이유

README는 한 줄짜리 설치 명령어로 시작합니다:

curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/octop/install.sh | bash

중요한 서버라면 이 방식을 권장하지 않습니다. 구체적인 이유는 해당 스크립트가 저장소(repository)에 포함되어 있지 않기 때문입니다. 이 스크립트는 Tencent Cloud Object Storage 버킷에서 제공됩니다. git 태그나 커밋으로 관리되지 않으므로, 오늘의 스크립트와 지난주의 스크립트를 비교(diff)할 수 없으며 변경 이력을 확인할 방법도 없습니다. 버킷은 내일 다른 내용을 제공할 수 있고, 프로젝트 내 그 무엇도 이를 기록하지 않습니다. 결과를 곧바로 bash로 파이프 연결하면, 스크립트 내용을 한 줄도 읽지 않은 상태에서 기기가 이를 실행하게 됩니다.

또한 이 설치 프로그램은 컨테이너가 아닌 호스트에 직접 기록합니다. uv를 사용하여 Python 3.12를 가져오고 패키지 관리자가 전혀 알지 못하는 환경을 구축하므로, 나중에 삭제하려면 수동으로 작업해야 합니다.

더 나은 두 가지 방법이 있습니다. 스크립트를 내려받아 내용을 확인한 뒤 실행하는 방법으로, 30초 정도 소요됩니다: curl -fsSL <url> -o install.sh을 실행한 다음 less install.sh, 그리고 bash install.sh를 차례로 수행하십시오. 아니면 이 가이드의 나머지 부분에서 다루는 Docker를 사용하십시오. PyPI 패키지(pip install octop)는 최소한 특정 릴리스에 고정할 수 있는 버전 관리된 아티팩트입니다.

Docker Compose를 사용하여 Octop 배포하기 (v0.9.19 버전 고정)

2026년 8월 기준으로 배포된 이미지가 없습니다. 제공된 Compose 파일은 저장소에서 직접 이미지를 빌드하므로, 버전을 고정하려면 git 태그를 체크아웃해야 합니다. 이는 대부분의 셀프 호스팅 프로젝트보다 한 단계 더 많은 과정이 필요한데, 예를 들어 셀프 호스팅 AFFiNE 워크스페이스는 배포된 이미지 태그를 고정하므로 VPS에서 직접 빌드할 필요가 없기 때문입니다. 아래의 클론, 체크아웃, 빌드 절차는 openGym 배포 가이드에서 다루는 방식과 동일하므로, 한 번이라도 설정해 본 적이 있다면 익숙할 것입니다.

git clone https://github.com/TencentCloud/Octop.git
cd Octop
git checkout v0.9.19

파일에 정의된 서비스 중 핵심 부분은 다음과 같습니다.

services:
  octop:
    build:
      context: ..
      dockerfile: docker/Dockerfile
    image: octop:latest
    container_name: octop
    restart: unless-stopped
    ports:
      - "${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"
    volumes:
      - ${OCTOP_DATA:-~/.octop}:/data/.octop
    environment:
      - HOME=/data
      - OCTOP_BIND_HOST=0.0.0.0
      - OCTOP_PORT=${OCTOP_PORT:-8088}
      - OCTOP_DEFAULT_PASSWORD=${OCTOP_DEFAULT_PASSWORD:-octop}
      - OCTOP_ADMIN_USERNAME=${OCTOP_ADMIN_USERNAME:-admin}
      - OPENAI_API_KEY=${OPENAI_API_KEY:-}

build: 블록을 확인하십시오. image: octop:latest는 레지스트리 참조가 아니라 사용자가 직접 빌드한 이미지의 이름이며, 따라서 latest은 가장 최근에 컴파일한 버전을 의미합니다. 데이터 경로는 기본값에 의존하지 말고 명시적으로 설정하며, 첫 부팅 전에 관리자 계정의 비밀번호를 실제 값으로 지정하십시오. 이를 docker/.env에 입력합니다.

OCTOP_PORT=8088
OCTOP_ADMIN_USERNAME=admin
OCTOP_DEFAULT_PASSWORD=<a long random password>
OCTOP_DATA=/srv/octop-data

이 파일에서 다른 부분보다 주의해야 할 함정이 하나 있습니다. Compose는 ${...} 플레이스홀더를 YAML에 삽입하기 위해서만 docker/.env을 읽습니다. 해당 파일에 키를 추가하더라도 Compose 파일의 environment: 항목에 나열되지 않으면 컨테이너로 전달되지 않습니다. OCTOP_ACCESS_TOKEN_TTL을 .env에만 추가하면 아무런 동작도 하지 않으며 오류 메시지도 출력되지 않습니다. 대안으로 마운트된 데이터 디렉터리 내의 ~/.octop/env에 동일한 키를 작성하면 Octop이 시작 시 이를 불러옵니다. Docker Compose의 env 파일 및 비밀 정보 가이드에서 이 두 메커니즘이 왜 다른지 설명합니다.

빌드 및 시작 명령어는 다음과 같습니다.

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml ps
curl http://127.0.0.1:8088/api/health

정상적인 인스턴스는 헬스 체크에 {"status":"ok","version":"..."}로 응답합니다. 다른 결과가 나오면 브라우저를 열기 전에 docker compose -f docker/docker-compose.yml logs -f octop를 확인하십시오.

이제 방금 빌드한 이미지에 의미 있는 이름을 부여하십시오. 다음 --build을 실행하면 octop:latest이 덮어쓰여 두 이미지를 구분할 수 없게 되기 때문입니다.

docker image tag octop:latest octop:0.9.19

첫 부팅 시 octop init이 실행되며 초기 자격 증명이 데이터 볼륨에 기록됩니다.

docker exec -it octop cat /data/.octop/credential.txt

기본값은 admin / octop이며, 이는 최초 초기화 시에만 적용됩니다. 사람들이 자주 묻는 질문에 대한 답이 여기에 있습니다. 컨테이너가 이미 한 번 시작된 후 OCTOP_DEFAULT_PASSWORD을 변경해도 계정이 이미 생성되어 있으므로 아무런 변화가 없습니다. 비밀번호는 대시보드에서 변경하십시오.

포트 8088을 공개하지 마십시오

위의 ports: 줄은 VPS의 모든 인터페이스에 바인딩됩니다. 컨테이너가 시작되는 즉시 대시보드가 기본 암호와 함께 평문으로 공용 인터넷에 노출됩니다. Octop의 자체 OCTOP_BIND_HOST 기본값은 127.0.0.1입니다. Compose 파일은 프로세스가 자체 네트워크 네임스페이스 외부의 트래픽을 수신해야 하므로 이를 0.0.0.0로 재정의합니다. 해당 재정의는 올바른 설정입니다. 사용자를 노출시키는 부분은 바로 게시된 포트입니다.

docker/docker-compose.yml의 ports: 줄을 수정하여 매핑이 루프백에서만 수신 대기하도록 하십시오:

    ports:
      - "127.0.0.1:${OCTOP_PORT:-8088}:${OCTOP_PORT:-8088}"

단순한 재정의 파일로 이 문제를 해결하려고 하지 마십시오. Compose는 ports 목록을 대체하는 대신 여러 파일에서 연결하므로, 결국 두 매핑이 모두 게시되고 두 번째 매핑은 바인딩에 실패하게 됩니다. 업스트림 파일을 그대로 유지하려면 시퀀스에 !override 태그를 사용하십시오. 이는 추가가 아닌 대체를 수행하는 문서화된 방법입니다. Compose가 여러 파일을 병합하는 방식에 대한 설명에서 나머지 병합 규칙을 확인할 수 있습니다.

루프백에 바인딩하면 방화벽에서 발생할 수 있는 문제도 해결됩니다. Docker는 게시된 포트 규칙을 ufw가 관리하는 체인보다 앞선 nat 테이블에 작성하므로, ufw deny 8088은 게시된 컨테이너 포트를 차단하지 못합니다. 127.0.0.1에 바인딩된 포트는 ufw의 설정과 관계없이 외부에서 접근할 수 없으며, 이것이 차선책이 아닌 올바른 해결 방법인 이유입니다.

리버스 프록시를 사용하여 TLS 적용하기

Caddy는 ACME(automatic certificate management environment)를 통해 인증서를 스스로 요청하고 별도의 설정 없이도 WebSocket을 프록시하므로 가장 간편한 방법입니다.

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx는 Octop이 WebSocket을 통해 채팅을 스트리밍하므로 더 세심한 설정이 필요합니다.

server {
    listen 443 ssl;
    server_name octop.example.com;

    ssl_certificate     /etc/letsencrypt/live/octop.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/octop.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

설정 파일의 모든 줄은 각자의 역할을 수행합니다. 채팅은 WS /agents/{id}/chat/ws를 통해 실행되므로, proxy_http_version 1.1 및 두 개의 upgrade 헤더가 없으면 nginx는 업그레이드 시도에 대해 400 Bad Request로 응답합니다. 이 경우 대시보드는 정상적으로 로드되지만, 사용자가 보내는 모든 메시지는 페이지에 오류가 표시되지 않은 채 무한히 대기 상태가 됩니다. proxy_buffering off는 인간 개입(human-in-the-loop) 재개 엔드포인트가 text/event-stream을 반환하기 때문에 중요하며, 프록시 버퍼에 담긴 SSE(server-sent events)가 스트리밍되지 않고 마지막에 한꺼번에 전달되는 현상을 방지합니다. proxy_read_timeout은 긴 도구 실행 시간을 처리합니다. 기본값인 60초가 지나면 에이전트 작업이 중단되고 upstream timed out (110: Connection timed out) 로그가 남기 때문입니다.

프록시 환경에서 JWT 인증 동작 방식

Octop은 쿠키가 아닌 Bearer 토큰으로 인증을 수행합니다. POST /api/auth/login는 {access_token, role, user, ...}을 반환하며, 이후 호출 시 Authorization: Bearer <access_token>을 포함합니다. 리버스 프록시 입장에서는 쿠키 도메인, Secure 플래그, SameSite 규칙 등을 잘못 설정할 위험이 없으므로, http://127.0.0.1:8088에서 정상 작동하던 세션은 https://octop.example.com에서도 동일하게 동작합니다.

실제 사용자를 서비스에 투입하기 전에 다음 두 가지 사항을 숙지해야 합니다.

WebSocket은 URL에 토큰을 포함합니다. 브라우저 JavaScript는 WebSocket 핸드셰이크 시 Authorization 헤더를 설정할 수 없으므로 엔드포인트는 WS /agents/{id}/chat/ws?token=<jwt>이 됩니다. TLS가 전송 중인 토큰을 보호하지만, 서버 로그까지 보호하지는 않습니다. Nginx는 기본적으로 쿼리 문자열을 포함한 전체 요청 라인을 access_log에 기록하므로, 실제 사용자의 유효한 토큰이 서버의 일반 텍스트 파일에 남게 됩니다. 인자를 제외한 경로만 기록하십시오. $uri은 쿼리 문자열이 제거된 정규화된 경로이므로, 이를 http 블록에 설정하고 서버에서 참조하십시오.

log_format octop_noargs '$remote_addr [$time_local] '
                        '"$request_method $uri $server_protocol" '
                        '$status $body_bytes_sent';
access_log /var/log/nginx/octop.log octop_noargs;

세션별 로그아웃 기능이 없습니다. OCTOP_ACCESS_TOKEN_TTL은 기본값이 86400이므로, 토큰은 로그인 후 24시간 동안 유효합니다. 문서화된 유일한 무효화 방법은 octop admin rotate-jwt-secret이며, 이는 ~/.octop/secrets/jwt_secret에 저장된 서명 키를 교체하여 모든 사용자의 기존 토큰을 즉시 무효화합니다. 따라서 팀원이 퇴사할 경우 사용자 삭제, 비밀 키 교체 순으로 진행한 뒤 나머지 사용자들에게 다시 로그인하도록 안내해야 합니다. 이 과정이 번거롭다면 토큰 수명을 단축하십시오. 이때 변수를 environment: 목록뿐만 아니라 .env에도 추가해야 함을 기억하십시오.

OCTOP_ACCESS_TOKEN_TTL=28800

무차별 대입 공격은 차단됩니다. OCTOP_LOGIN_MAX_ATTEMPTS은 기본값이 5회 실패이며 OCTOP_LOGIN_LOCKOUT_SECONDS은 900초이므로, 계정이 잠긴 사용자는 설치 오류를 겪는 대신 15분 동안 대기하게 됩니다. Octop은 자체 사용자 저장소를 사용하며 v0.9.19 기준 OIDC 지원이 문서화되어 있지 않습니다. 따라서 본격적인 SSO(Single Sign-On)가 필요하다면 앞단에 인증 프록시를 배치해야 하며, 이때 자체 호스팅 Authentik 서버를 사용할 수 있습니다.

모델 백엔드를 Octop에 연결하기

공급자는 대시보드에서 에이전트별로 설정하며, octop provider list에서 현재 설정을 확인할 수 있습니다. Octop은 OpenAI 호환 API, DashScope(Qwen), Ollama에 대한 사전 설정을 제공하며, 자격 증명은 사용자의 SQLite 데이터베이스 내 providers 테이블에 저장됩니다. 선택에 따라 비용과 외부로 전송되는 데이터 범위가 달라집니다.

Ollama를 이용한 로컬 모델. 서버 외부로 데이터가 나가지 않으며, 토큰 비용 대신 RAM 자원을 사용합니다. 사용자가 자주 실수하는 연결 설정은 다음과 같습니다. 컨테이너는 127.0.0.1:11434의 호스트 Ollama에 직접 접근할 수 없는데, 해당 주소가 컨테이너 자신의 루프백 주소이기 때문입니다. 서비스에 호스트 게이트웨이 항목을 추가하십시오.

    extra_hosts:
      - "host.docker.internal:host-gateway"

그런 다음 공급자 기본 URL을 Ollama의 OpenAI 호환 경로인 http://host.docker.internal:11434/v1로 설정하십시오. API 키 필드에는 빈 문자열이 아닌 아무 값이나 입력하십시오. Ollama는 이를 무시하지만, OpenAI 클라이언트는 빈 키를 허용하지 않기 때문입니다. 이 설정이 작동하려면 Ollama가 루프백 외부에서도 수신 대기해야 하며, 이는 systemd 유닛에 OLLAMA_HOST=0.0.0.0:11434를 설정해야 함을 의미합니다. 이는 위험 요소가 있습니다. Ollama는 인증 기능이 없으므로, 공인 IP에서 11434 포트를 개방하면 누구든 스캔을 통해 모델 서버를 무단으로 사용할 수 있습니다. Docker의 사설 대역인 sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp만 허용하고 나머지는 차단하십시오. VPS에서 Ollama 실행하기에서 모델 크기 산정을 다루며, Ollama와 vLLM 비교에서 Ollama가 적합하지 않은 상황을 설명합니다.

로컬 모델 사용 시 주의할 점이 하나 더 있습니다. Octop의 버그처럼 보이지만 실제로는 그렇지 않은 경우입니다. 에이전트는 도구를 호출하여 작동하며, 시스템 프롬프트와 도구 정의, 대화 기록을 합치면 프롬프트가 매우 커집니다. Ollama는 기본적으로 적당한 크기의 컨텍스트 윈도우를 제공하므로, 도구 정의가 포함된 프롬프트 앞부분이 윈도우에서 밀려날 수 있습니다. 이 경우 모델은 도구 호출을 멈추거나 존재하지 않는 도구를 만들어냅니다. num_ctx를 16k 또는 32k로 높이고 함수 호출 능력이 검증된 모델을 선택하십시오. 답변이 문장 중간에 끊기는 것은 이와 반대되는 문제이며 num_predict 설정과 관련이 있습니다. 답변이 잘려서 온다면 num_predict 설정 위치와 done_reason의 내용을 먼저 확인한 뒤 에이전트의 문제를 의심하십시오. 후보군 중에서 선택하기보다 특정 모델로 시작하고 싶다면 Nemotron 3.5 Lightning을 시도해 볼 가치가 있습니다. 해당 문서에는 가져올 정확한 태그, 필요한 RAM 용량, CPU만으로 구동 가능한지 여부가 명시되어 있습니다.

자체 호스팅 게이트웨이. Octop과 다른 서비스 사이에 자체 호스팅 LiteLLM 게이트웨이를 두면 단일 기본 URL, 사용자별 개별 키, 지출 한도 설정, 통합 로그 관리가 가능합니다. 또한 Octop 설정을 수정하지 않고도 배후의 모델을 교체할 수 있습니다.

유료 API. 최고의 품질을 제공하지만, 대화 내용이 서버를 벗어나 공급자에게 전달된다는 명확한 트레이드오프가 있습니다. 이는 자체 호스팅을 선택하는 주된 이유와 상충합니다. 키는 docker/.env에 OPENAI_API_KEY 형식으로 입력하며, Compose 파일은 이미 이를 전달하도록 설정되어 있습니다.

어떤 방식을 선택하든 Compose 파일은 OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL를 포함하고 있습니다. 이를 통해 자체 Langfuse 인스턴스로 추적 데이터를 전송하여, 채팅 창에서 추측하는 대신 에이전트의 실제 동작을 확인할 수 있습니다.

사용자, 역할 및 공유 에이전트 라이브러리

최초 부팅 시 생성된 관리자 계정이 다른 계정을 생성하고 관리합니다. 각 사용자는 고유한 에이전트, 작업 공간, 자격 증명을 가지며, 이러한 격리는 브라우저가 보유한 토큰을 통해 유지됩니다. 이와 더불어 누구나 사용할 수 있는 기술 및 하위 에이전트 공유 풀이 존재합니다. 이는 가족 단위로 이 서비스를 운영할 때 유용한 기능으로, 한 사람이 우수한 연구용 에이전트를 한 번 구축해 두면 다른 사람들은 이를 다시 만들 필요가 없습니다.

도구 사용 시 주의가 필요합니다. Octop은 도구 승인 및 셸 명령 가드레일을 제공하며 두 기능 모두 실제로 작동하지만, 셸 명령을 실행하는 에이전트는 데이터 볼륨이 마운트된 Octop 컨테이너 내부에서 명령을 수행합니다. 가드레일은 부주의한 프롬프트로 발생할 수 있는 피해를 줄여줄 뿐입니다. 이는 샌드박스 경계가 아니므로, 셸 접근 권한을 직접 주지 않을 사용자에게는 반드시 도구 승인 기능을 켜두어야 합니다. 다른 옵션과 비교 중이라면 셀프 호스팅 AI 에이전트 요약에서 각 서비스가 이 문제를 어떻게 처리하는지 비교해 볼 수 있습니다.

이렇게 빠르게 릴리스되는 프로젝트 업그레이드하기

[
  {
    "version": "v0.9.16",
    "days_since_previous_release": 2
  },
  {
    "version": "v0.9.17",
    "days_since_previous_release": 3
  },
  {
    "version": "v0.9.18",
    "days_since_previous_release": 1
  },
  {
    "version": "v0.9.19",
    "days_since_previous_release": 3
  }
]

위 날짜는 2026년 8월 7일 기준으로 저장소에 기록된 태그 날짜입니다. 9일 동안 4개의 릴리스가 배포되었으며, 가장 짧은 간격은 1일이었고, v0.9.19 버전은 이전 태그로부터 3일 만에 출시되었습니다. 이러한 릴리스 주기는 프로젝트가 활발하다는 좋은 신호이지만, latest을 무작정 실행하기에는 위험한 이유가 됩니다. 변경 사항을 적용하기 전에 반드시 내용을 확인하십시오.

cd Octop
git fetch --tags
git tag --sort=-creatordate | head
NEW_TAG=$(git tag --sort=-creatordate | head -1)
git log --oneline "v0.9.19..$NEW_TAG"

데이터베이스 마이그레이션은 시작 시점에 실행되며, 1.0 버전 이전의 프로젝트에서 마이그레이션이 실패하면 사용자가 직접 복구해야 하므로 매번 반드시 백업을 수행하십시오.

docker compose -f docker/docker-compose.yml stop
sudo tar czf octop-backup-$(date +%F).tgz -C /srv octop-data
docker compose -f docker/docker-compose.yml start

그다음 새로운 태그를 체크아웃하고 docker compose -f docker/docker-compose.yml up -d --build를 사용하여 다시 빌드하십시오. 만약 문제가 발생하면 이전 태그를 체크아웃하고 다시 빌드하여 코드를 복구할 수 있지만, 데이터베이스를 복구하려면 tarball이 필요합니다.

해당 tarball에는 octop.db, config.json, JWT 서명 비밀 키, credential.txt이 포함되어 있으므로 서버 자체만큼이나 보안에 주의해야 합니다. 파일 모드를 600으로 유지하고 사본을 서버 외부의 안전한 곳에 보관하십시오. 대규모 설치의 경우, 이 프로젝트는 SQLite 대신 pgvector가 포함된 PostgreSQL을 실행하는 docker/docker-compose.postgres.yml도 제공합니다.

실패 유형 및 확인 가능한 메시지

상태 확인(health check) 응답이 없습니다. curl http://127.0.0.1:8088/api/health가 멈추거나 거부합니다. docker compose -f docker/docker-compose.yml logs -f octop을 읽어 보십시오. 초기화 도중 종료되는 컨테이너는 대개 데이터 디렉터리에 쓰기 권한이 없는 경우이므로, OCTOP_DATA에 설정한 경로의 소유권을 확인하십시오.

대시보드는 로드되지만 채팅이 멈춥니다. 페이지에 오류는 없으나 응답이 전혀 없습니다. 브라우저 콘솔을 열고 wss://octop.example.com/agents/.../chat/ws로의 연결 실패 여부를 확인하십시오. 프록시가 업그레이드 요청을 전달하지 못하는 상태입니다. proxy_http_version 1.1과 Upgrade, Connection 헤더를 추가하십시오.

응답 전체가 몇 초 뒤 한꺼번에 나타납니다. 스트리밍은 작동 중이나 버퍼링이 활성화된 상태입니다. proxy_buffering off을 설정하십시오.

bind: address already in use. 이미 다른 프로세스가 8088 포트를 점유하고 있습니다. sudo ss -tlnp | grep 8088 명령으로 해당 프로세스를 확인할 수 있습니다. 원본 파일을 수정하는 대신 override 파일에 ports 항목을 중복 추가했을 때도 이 오류가 발생합니다.

올바른 비밀번호를 입력해도 거부됩니다. 비밀번호를 5회 잘못 입력하면 900초 동안 잠금 상태가 됩니다. 재설치하지 말고 잠금이 풀릴 때까지 기다리십시오.

.env의 새 비밀번호가 적용되지 않습니다. 해당 자격 증명은 최초 초기화 시에만 적용됩니다. 대시보드에서 비밀번호를 변경하십시오.

에이전트가 응답은 하지만 도구를 실행하지 않습니다. 거의 항상 로컬 모델 문제입니다. 컨텍스트 윈도우가 도구 정의를 담기에 너무 작거나, 모델의 함수 호출(function calling) 능력이 부족한 경우입니다. num_ctx을 높이고 도구 사용에 최적화된 모델을 사용해 보십시오.

FAQ

Octop은 Open WebUI를 대체할 수 있습니까?

추가된 기능이 필요한 경우에만 그렇습니다. Open WebUI는 모델을 위한 채팅 인터페이스이며, 개인이나 신뢰할 수 있는 가구 단위에서 사용하기에 충분히 훌륭합니다. Octop은 관리자 역할이 포함된 계정, 사용자별 작업 공간 및 자격 증명, 전환 가능한 전문가 에이전트 라이브러리를 추가하므로 여러 사람이 하나의 서버를 공유하면서도 대화 기록을 분리할 수 있습니다. 단일 계정으로 충분하다면 Open WebUI가 더 단순하고 훨씬 성숙한 선택입니다.

Octop curl 설치 스크립트를 사용하지 말아야 하는 이유는 무엇입니까?

해당 스크립트는 저장소가 아닌 Tencent Cloud Object Storage 버킷에서 제공되므로 git 태그나 커밋으로 관리되지 않습니다. 오늘 실행되는 스크립트가 지난주와 어떻게 다른지 비교할 수 없으며, bash로 파이프를 연결하면 내용을 읽기도 전에 실행됩니다. 또한 패키지 관리자 외부에서 자체 Python 3.12 환경을 사용하여 호스트에 설치됩니다. 스크립트를 먼저 다운로드하여 읽어보거나, 체크아웃된 태그를 사용하여 Docker Compose로 배포하십시오.

Octop에서 유료 API 대신 로컬 모델을 사용할 수 있습니까?

네, 가능합니다. Octop은 OpenAI 호환 API를 지원하며 Ollama 프리셋을 제공합니다. 컨테이너에 extra_hosts: ["host.docker.internal:host-gateway"]를 추가하고 호스트에 OLLAMA_HOST=0.0.0.0:11434를 설정하면 http://host.docker.internal:11434/v1을 통해 연결할 수 있습니다. Ollama 자체에는 인증 기능이 없으므로 방화벽에서 11434 포트를 Docker 주소 범위로 제한하십시오. 도구 정의가 포함된 에이전트 프롬프트는 기본 컨텍스트 윈도우를 초과하여 모델이 도구 호출을 중단할 수 있으므로, Ollama의 num_ctx을 16k 이상으로 높이는 것이 좋습니다.

리버스 프록시가 필요합니까, 아니면 8088 포트를 직접 열어도 됩니까?

프록시가 반드시 필요합니다. Octop의 기본 Compose 파일은 TLS 없이 모든 인터페이스에 8088 포트를 노출하므로, 비밀번호와 베어러 토큰이 평문으로 인터넷을 통해 전송됩니다. 노출 포트를 127.0.0.1:8088:8088로 변경하고 Caddy나 nginx를 앞단에 두어 인증서를 적용하십시오. nginx를 사용하는 경우 WebSocket 업그레이드 헤더를 전달하고 proxy_buffering off을 설정해야 합니다. 그렇지 않으면 페이지는 로드되지만 채팅 응답이 오지 않을 수 있습니다.

Octop은 운영 환경에서 사용할 준비가 되었습니까?

2026년 8월 기준으로 1.0 버전 이전이며 매주 여러 개의 태그된 릴리스가 배포되고 있으므로, 안정된 소프트웨어라기보다 발전 가능성이 있는 단계로 간주해야 합니다. 특정 태그를 고정하고, 업그레이드 전마다 커밋 로그를 확인하며, 재빌드 전마다 데이터 볼륨을 백업한다면 가족이나 소규모 내부 팀에서 사용하기에는 적합합니다. latest에서 실행하지 마시고, 아직 고객 데이터를 저장하지 마십시오.