SSD Nodes Learn Hosting plans →
Hướng dẫn Matt ConnorBởi Matt Connor

Tự host Octop trên VPS bằng Docker Compose

Hướng dẫn chạy Octop v0.9.19 trên VPS bằng Docker Compose ghim tag, tách user, nối model backend tương thích OpenAI, bật TLS và tránh curl installer.

Octop là gì và vì sao bạn nên tự host

Octop là một AI assistant tự host cho gia đình hoặc nhóm nhỏ. Lý do tự host Octop thay vì dùng một giao diện chat đơn giản là Octop tách biệt người dùng với nhau. Open WebUI cung cấp giao diện trình duyệt phía trước model, đồng thời hỗ trợ nhiều người dùng và quyền truy cập. Octop kết hợp account có role admin, workspace riêng và bộ credential riêng cho từng người dùng, cùng một thư viện các agent chuyên biệt để mỗi người dùng chuyển đổi theo từng tác vụ. Đây là điểm khác biệt giúp một VPS phục vụ 5 người thay vì chỉ 1 người.

Project được lưu tại github.com/TencentCloud/Octop. Đây là một process cung cấp web dashboard, command line interface, các kênh chat (Feishu, DingTalk, QQ, Discord, WeCom) và các job được lập lịch, tất cả đều dùng chung một cơ sở dữ liệu SQLite bên dưới ~/.octop/. Toàn bộ nội dung dưới đây được viết theo tag v0.9.19, phát hành ngày 5 August 2026. Nếu bạn vẫn đang chọn giữa các platform, bài so sánh các lựa chọn thay thế Open WebUI có thể chạy trên VPS sẽ bao quát phạm vi rộng hơn.

Có một điểm cần làm rõ trước khi bạn dành cả buổi tối cho việc này. Khi hướng dẫn này được viết, Octop là phần mềm trước phiên bản 1.0, được phát hành từ tổ chức GitHub của một vendor. Sau đó project đã gắn tag v1.0.0 vào ngày 14 September 2026. Tính đến ngày 20 November 2026, tag mới nhất là v1.0.3b7, được phát hành ngày 18 November 2026, và repository có khoảng 12,300 star. Bản stable release mới nhất vẫn là v1.0.2, được phát hành ngày 18 October 2026. Các bước bên dưới được viết theo v0.9.19 và chưa được kiểm thử lại trên 1.x. Project thay đổi nhanh, thể hiện rõ qua các version number, và nội dung này không cam kết một lộ trình upgrade ổn định. Hãy pin một tag, đọc changelog và luôn giữ backup.

Bạn cần chuẩn bị gì trước khi bắt đầu

  • Một VPS chạy Ubuntu 24.04 với Docker Engine và Compose plugin. Nếu bạn chưa quen với Compose, hãy bắt đầu với kiến thức cơ bản về Docker Compose cho VPS.
  • git, vì bạn sẽ checkout một release tag thay vì pull một image.
  • Một domain trỏ đến VPS, vì bạn muốn đặt TLS (bảo mật tầng truyền tải) phía trước dịch vụ này.
  • Một model backend hỗ trợ OpenAI API: Ollama chạy cục bộ, gateway tự host hoặc key trả phí.

Bản thân Octop khá nhẹ. Đây là một tiến trình Python và một file SQLite. Phần nặng nằm ở model backend. Vì vậy, nếu dự định chạy model trên cùng máy, hãy chọn cấu hình máy đủ đáp ứng model.

Vì sao chúng tôi không khuyến nghị dùng trình cài đặt qua curl

README của v0.9.19 mở đầu bằng lệnh cài đặt một dòng:

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

Chúng tôi không khuyến nghị pipe trực tiếp lệnh này vào bash trên một server mà bạn cần bảo vệ. Repository có chứa scripts/install.sh, nên bản sao đó có git history và được gắn với một tag. Bản sao được cung cấp từ bucket Tencent Cloud Object Storage không được pin bởi lệnh trên. Bucket có thể cung cấp nội dung khác vào ngày mai, nhưng lệnh vẫn sẽ chạy nội dung đó. Pipe kết quả trực tiếp vào bash cũng có nghĩa là máy sẽ chạy script trước khi bạn đọc dù chỉ một dòng.

Installer cũng ghi trực tiếp vào host thay vì container. Nó dùng uv để tải Python 3.12 và build một environment mà package manager của bạn không biết đến, nên sau này bạn phải gỡ thủ công.

Có 2 lựa chọn tốt hơn. Tải script xuống, đọc script, rồi chạy nó; việc này chỉ mất 30 giây: curl -fsSL <url> -o install.sh, sau đó less install.sh, rồi bash install.sh. Hoặc dùng Docker, đây là nội dung còn lại của hướng dẫn này. Package trên PyPI (pip install octop) ít nhất là một artifact có version, nên bạn có thể pin vào một release.

Triển khai Octop bằng Docker Compose, pin về v0.9.19

File Compose được phát hành cùng v0.9.19 build image từ repository. Vì vậy, trong hướng dẫn này, pin một version nghĩa là checkout một git tag. Project có phát hành image. Cây mã v0.9.19 đã có workflow docker-publish.yml, được thêm từ v0.9.8 vào ngày 15 July 2026. Workflow này build image và push image lên Docker Hub cho mỗi tag v*. Tính đến ngày 20 October 2026, project cũng phát hành image lên container registry của GitHub (docker pull ghcr.io/tencentcloud/octop:1.0.2). Build từ tag đã checkout vẫn là cách pin chặt hơn, vì bạn compile đúng code mình đã đọc thay vì tin vào một registry tag. Cách này nhiều hơn một bước so với yêu cầu của phần lớn project tự host. Ví dụ, một workspace AFFiNE tự host pin vào một image tag đã phát hành và không build gì trên VPS. Quy trình clone, checkout và build bên dưới cũng giống quy trình trong hướng dẫn triển khai openGym, nên nếu đã thiết lập một lần thì bạn đã biết cấu trúc của nó.

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

Đây là service mà file định nghĩa, đã lược bớt các phần cần thiết:

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:-}

Lưu ý block build:. image: octop:latest là tên của build riêng của bạn, không phải một registry reference. Vì vậy, latest ở đây có nghĩa là image bạn compile gần đây nhất. Đặt data path tại một vị trí cụ thể thay vì dùng giá trị mặc định, và đặt mật khẩu thật cho admin account trước lần boot đầu tiên. Đặt nội dung này vào docker/.env:

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

Có một điểm dễ mắc lỗi ở đây quan trọng hơn các phần còn lại của file. Compose chỉ đọc docker/.env để interpolate các placeholder ${...} trong YAML. Key bạn thêm vào file đó không được truyền vào container nếu chưa được liệt kê dưới environment: trong file Compose. Chỉ thêm OCTOP_ACCESS_TOKEN_TTL vào .env sẽ không có tác dụng gì, và cũng không báo lỗi. Cách khác là ghi các key tương tự vào ~/.octop/env trong data directory được mount; Octop sẽ load file này khi khởi động. Hướng dẫn về env file và secret trong Docker Compose giải thích vì sao hai cơ chế này không giống nhau.

Build và khởi động service:

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

Instance hoạt động bình thường sẽ trả về health check một JSON object có dạng như {"ok":true,"started_at":...,"db":...,"users_loaded":0,"agents_running":0}. Nếu kết quả khác, hãy đọc docker compose -f docker/docker-compose.yml logs -f octop trước khi mở browser.

Bây giờ hãy đặt cho image vừa build một tên dễ nhận biết. Lần --build tiếp theo sẽ ghi đè octop:latest, khiến bạn không còn cách nào phân biệt hai image:

docker image tag octop:latest octop:0.9.19

Lần boot đầu tiên chạy octop init và ghi credential ban đầu vào data volume:

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

Giá trị mặc định là admin / octop và chỉ được áp dụng trong lần init đầu tiên. Đây là lý do cho câu hỏi thường gặp: thay đổi OCTOP_DEFAULT_PASSWORD sau khi container đã khởi động một lần sẽ không thay đổi gì, vì account đã tồn tại. Hãy đổi mật khẩu trong dashboard.

Không publish port 8088

Dòng ports: ở trên bind trên mọi interface của VPS. Ngay khi container khởi động, dashboard đã nằm trên Internet công khai dưới dạng plaintext. Mặc định 127.0.0.1 của Octop là OCTOP_BIND_HOST; file Compose override thành 0.0.0.0 vì process phải nhận traffic từ bên ngoài network namespace của chính nó. Override đó là đúng. Vấn đề nằm ở port được publish vì nó làm lộ dịch vụ ra ngoài.

Sửa dòng ports: trong docker/docker-compose.yml để mapping chỉ listen trên loopback:

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

Không cố sửa việc này bằng một file override thông thường. Compose nối các list ports từ nhiều file thay vì thay thế chúng, nên cuối cùng bạn sẽ publish cả hai mapping và mapping thứ hai sẽ fail khi bind. Nếu muốn giữ nguyên file upstream, hãy dùng tag !override trên sequence. Đây là cách được tài liệu hướng dẫn để thay thế thay vì nối thêm. Phần giải thích cách Compose merge nhiều file trình bày các quy tắc merge còn lại.

Bind vào loopback cũng giải quyết vấn đề bạn sẽ gặp với firewall. Docker ghi các rule cho port đã publish vào bảng nat, trước các chain do ufw quản lý, nên ufw deny 8088 không chặn được port của container đã publish. Trên Docker Engine 28.0.0 trở lên, port bind vào 127.0.0.1 sẽ không thể truy cập từ bên ngoài, bất kể ufw được cấu hình thế nào. Vì vậy đây là cách sửa đúng, không phải phương án tạm thời. Các bản Engine cũ hơn cho phép host trong cùng L2 segment, chẳng hạn các máy khác trên switch của nhà cung cấp, truy cập những port được publish vào localhost. Vì vậy hãy chạy docker version và upgrade nếu server báo phiên bản thấp hơn 28.

Đặt TLS phía trước bằng reverse proxy

Caddy là cách triển khai ngắn gọn nhất vì tự yêu cầu chứng chỉ qua ACME (môi trường quản lý chứng chỉ tự động) và tự proxy WebSocket mà không cần cấu hình thêm:

octop.example.com {
    reverse_proxy 127.0.0.1:8088
}

nginx cần cấu hình cẩn thận hơn vì Octop truyền chat qua 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;
    }
}

Mỗi dòng trong đó đều có tác dụng. Chat chạy qua WS /api/agents/{id}/chat/ws, nên nginx phải chuyển tiếp 2 upgrade header và dùng HTTP/1.1 với upstream; proxy_http_version 1.1 chỉ rõ điều này và cần thiết trên các phiên bản nginx trước 1.29.7. Nếu upgrade không thành công, dashboard vẫn tải bình thường nhưng chat không thể kết nối; v0.9.19 kết thúc trạng thái streaming sau khi handshake thất bại thay vì để message treo mãi. proxy_buffering off quan trọng vì endpoint resume human-in-the-loop trả về text/event-stream, còn SSE (server-sent events) bị giữ trong proxy buffer sẽ đến cùng một lúc ở cuối thay vì được stream liên tục. proxy_read_timeout xử lý các khoảng thời gian dài không có dữ liệu từ upstream: giá trị mặc định 60 giây có thể ngắt WebSocket và ghi log upstream timed out (110: Connection timed out), nhưng v0.9.19 vẫn cho task của agent tiếp tục chạy sau khi bị ngắt kết nối. Thao tác cancel rõ ràng sẽ dừng task.

Cơ chế xác thực JWT phía sau proxy

Octop xác thực bằng bearer token, không phải cookie. POST /api/auth/login trả về {access_token, token_type, expires_in, user}, các request sau đó gửi kèm Authorization: Bearer <access_token>. Với reverse proxy, đây là điểm thuận lợi: không có cookie domain, không có flag Secure và không có rule SameSite dễ cấu hình sai. Vì vậy, session hoạt động trên http://127.0.0.1:8088 sẽ hoạt động giống hệt trên https://octop.example.com.

Bạn cần biết 2 hệ quả sau trước khi đưa hệ thống cho người dùng thật.

WebSocket gửi token trong URL. Endpoint là WS /api/agents/{id}/chat/ws?token=<jwt> vì JavaScript trong trình duyệt không thể đặt header Authorization cho WebSocket handshake. TLS bảo vệ token khi truyền qua mạng. Nhưng TLS không bảo vệ token khỏi chính log của bạn: nginx mặc định ghi toàn bộ request line, bao gồm cả query string, vào access_log. Vì vậy, token đang hoạt động của người dùng thật sẽ nằm trong file plaintext trên server. Hãy ghi log path mà không có arguments. $uri là path đã chuẩn hóa và đã bỏ query string, nên hãy đặt cấu hình này trong block http rồi tham chiếu nó từ server:

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;

Logout không revoke token trong v0.9.19. OCTOP_ACCESS_TOKEN_TTL mặc định là 86400, nên token vẫn hợp lệ trong 24 giờ sau khi đăng nhập. Cách duy nhất được tài liệu ghi nhận để vô hiệu hóa token là octop admin rotate-jwt-secret. Thao tác này rotate signing key được lưu tại ~/.octop/secrets/jwt_secret và lập tức vô hiệu hóa mọi token còn hiệu lực của tất cả người dùng. Vì vậy, khi một người rời nhóm, thứ tự thực hiện là: xóa user, rotate secret, rồi yêu cầu những người còn lại đăng nhập lại. Nếu cách này quá nặng, hãy rút ngắn thời gian hiệu lực và nhớ thêm biến đó vào danh sách environment: cũng như .env:

OCTOP_ACCESS_TOKEN_TTL=28800

Cơ chế chống brute force đã được tích hợp: OCTOP_LOGIN_MAX_ATTEMPTS mặc định là 5 lần thất bại và OCTOP_LOGIN_LOCKOUT_SECONDS là 900, nên user bị khóa chỉ cần chờ 15 phút thay vì tưởng rằng hệ thống bị hỏng. Octop có user store riêng và chưa có tài liệu về hỗ trợ OIDC trong v0.9.19. Vì vậy, nếu cần single sign-on thực sự, bạn phải đặt một authenticating proxy phía trước Octop. Đây là mục đích của server Authentik tự host. Hỗ trợ OIDC tích hợp được bổ sung trong v0.9.24 vào ngày 15 tháng 8 năm 2026.

Trỏ Octop đến backend model

Provider được cấu hình riêng cho từng agent trong dashboard, còn octop provider list cho biết cấu hình hiện tại. Octop có sẵn preset cho API tương thích OpenAI, DashScope (Qwen) và Ollama. Thông tin xác thực được lưu trong bảng providers của SQLite database trên chính máy của bạn. Lựa chọn này quyết định chi phí và dữ liệu nào rời khỏi máy chủ.

Model local với Ollama. Không có dữ liệu nào rời khỏi server, và chi phí nằm ở RAM thay vì token. Chi tiết kết nối thường gây nhầm lẫn: container không thể truy cập Ollama trên host tại 127.0.0.1:11434, vì địa chỉ đó là loopback của chính container. Thêm một host gateway entry vào service:

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

Sau đó đặt base URL của provider thành http://host.docker.internal:11434/v1, đây là path tương thích OpenAI của Ollama. Điền một chuỗi bất kỳ không rỗng vào trường API key, vì Ollama bỏ qua giá trị này nhưng các client OpenAI sẽ từ chối gửi request nếu trường này rỗng. Ollama cũng phải listen ngoài loopback thì cách này mới hoạt động. Cụ thể, cần đặt OLLAMA_HOST=0.0.0.0:11434 trong systemd unit của Ollama. Đây là phần rủi ro: local API của Ollama không yêu cầu authentication, nên cổng 11434 mở trên public IP sẽ biến thành model server miễn phí cho bất kỳ ai scan thấy nó trước. Chỉ cho phép private range của Docker, sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp, và deny toàn bộ phần còn lại. Chạy Ollama trên VPS trình bày cách chọn kích thước model, còn so sánh Ollama và vLLM giải thích khi nào Ollama không còn là server phù hợp.

Có thêm một cảnh báo về model local vì lỗi này trông giống bug trong Octop nhưng thực ra không phải. Agent hoạt động bằng cách gọi tool, nên system prompt, định nghĩa tool và history tạo thành một prompt lớn. Context window mặc định của Ollama hiện phụ thuộc vào VRAM: 4k khi dưới 24 GiB, 32k từ 24 GiB đến dưới 48 GiB, và 256k khi đạt 48 GiB trở lên. Hướng dẫn hiện tại của Ollama khuyến nghị ít nhất 64,000 token cho agent và coding tool. Đặt num_ctx để workload nằm trong context được model hỗ trợ và lượng memory khả dụng, đồng thời chọn model thực sự tốt ở function calling. Reply dừng giữa câu là vấn đề ngược lại và dùng một setting khác, num_predict. Vì vậy, nếu câu trả lời bị truncated, hãy kiểm tra nơi đặt num_predict và giá trị của done_reason trước khi quy lỗi cho agent. Nếu muốn bắt đầu từ một model cụ thể thay vì một shortlist, Nemotron 3.5 Lightning là lựa chọn đáng thử. Bài viết đó cung cấp tag chính xác cần pull, lượng RAM model yêu cầu và khả năng chạy kịp khi chỉ dùng CPU.

Gateway tự host. Đặt LiteLLM gateway tự host giữa Octop và mọi thành phần còn lại. Bạn sẽ có một base URL, key riêng cho từng user, giới hạn chi phí và một log duy nhất. Bạn cũng có thể đổi model phía sau gateway mà không cần sửa gì trong Octop.

API trả phí. Chất lượng tốt nhất, nhưng có đánh đổi rõ ràng: nội dung hội thoại rời khỏi server và được gửi đến provider, trong khi đây lại là một trong những lý do chính để self-host. Key được đặt trong docker/.env dưới dạng OPENAI_API_KEY; Compose file đã truyền giá trị này qua.

Dù chọn phương án nào, Compose file cũng chứa OCTOP_LANGFUSE_ENABLED, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY và LANGFUSE_BASE_URL. Nhờ đó, bạn có thể gửi trace đến instance Langfuse của mình và biết chính xác agent đang làm gì thay vì đoán từ cửa sổ chat.

Người dùng, role và thư viện agent dùng chung

Tài khoản admin được tạo trong lần boot đầu tiên sẽ tạo và quản lý các tài khoản khác. Mỗi người dùng có agent, workspace và credential riêng. Cơ chế cô lập này được thực thi bằng token mà trình duyệt lưu giữ. Ngoài ra còn có các template chuyên gia đi kèm và các gói skill ở cấp instance. Tính năng chia sẻ agent của bạn với người dùng khác được bổ sung trong v0.9.24, sau phiên bản được ghim trong hướng dẫn này.

Hãy cẩn thận khi dùng các công cụ. Octop cung cấp tính năng phê duyệt tool và các guardrail cho lệnh shell; cả hai đều hoạt động thật. Tuy nhiên, agent chạy lệnh shell bên trong container Octop, nơi volume dữ liệu của bạn được mount. Guardrail hạn chế những gì một prompt bất cẩn có thể thực hiện. Chúng không tạo ra ranh giới sandbox. Vì vậy, hãy bật phê duyệt tool đối với bất kỳ ai mà bạn không muốn cấp quyền chạy shell. Nếu bạn đang cân nhắc các lựa chọn khác, bài tổng hợp về các AI agent tự host so sánh cách từng lựa chọn xử lý vấn đề này.

Nâng cấp một dự án phát hành nhanh như vậy

Biểu đồDays between Octop releases, v0.9.16 to v0.9.19 (repository tags, 7 August 2026)
Dữ liệu đằng sau biểu đồ này
[
  {
    "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
  }
]

Đó là các ngày gắn tag từ repository, tính đến ngày 7 tháng 8 năm 2026. 4 bản phát hành được gắn tag đã xuất hiện trong 9 ngày, với khoảng cách ngắn nhất là 1 ngày, và v0.9.19 xuất hiện sau 3 ngày so với tag trước đó. Nhịp phát hành này là dấu hiệu tốt cho dự án nhưng là lý do không tốt để chạy latest. Hãy đọc các thay đổi trước khi áp dụng:

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"

Kiểm tra $NEW_TAG thực sự chứa gì trước khi checkout, vì project gắn tag cho cả các bản beta như v1.0.2b9 cùng với các bản stable. Tính đến ngày 20 tháng 11 năm 2026, tag mới nhất là v1.0.3b7, được phát hành ngày 18 tháng 11 năm 2026; bản stable mới nhất vẫn là v1.0.2, được phát hành ngày 18 tháng 10 năm 2026. Việc nâng cấp từ v0.9.19 đi qua bản phát hành v1.0.0 ngày 14 tháng 9 năm 2026, nên log này dài và đáng để đọc kỹ.

Mỗi lần đều phải backup trước, vì database migration chạy khi startup và một migration lỗi trên dự án phát hành nhanh như vậy sẽ trở thành vấn đề bạn phải tự xử lý:

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

Sau đó checkout tag mới và rebuild bằng docker compose -f docker/docker-compose.yml up -d --build. Nếu có lỗi, checkout tag cũ rồi rebuild sẽ khôi phục code, nhưng chỉ tarball mới khôi phục được database.

Tarball đó chứa octop.db, config.json, JWT signing secret và credential.txt, nên nhạy cảm không kém chính server. Giữ file ở mode 600 và lưu một bản sao bên ngoài máy chủ. Với hệ thống lớn hơn, project cũng cung cấp docker/docker-compose.postgres.yml, chạy PostgreSQL với pgvector thay vì SQLite.

Các lỗi thường gặp và chuỗi bạn sẽ thấy

Health check không bao giờ phản hồi. curl http://127.0.0.1:8088/api/health bị treo hoặc từ chối kết nối. Đọc docker compose -f docker/docker-compose.yml logs -f octop. Container thoát trong lần khởi tạo đầu tiên thường không ghi được vào thư mục dữ liệu. Hãy kiểm tra owner của đường dẫn bạn đã đặt cho OCTOP_DATA.

Dashboard tải được nhưng chat không thể kết nối. WebSocket handshake thất bại sẽ kết thúc trạng thái streaming trong v0.9.19. Mở browser console và tìm kết nối thất bại đến wss://octop.example.com/api/agents/.../chat/ws. Kiểm tra proxy có forward upgrade hay không. Thêm header proxy_http_version 1.1, Upgrade và Connection.

Toàn bộ câu trả lời xuất hiện cùng lúc sau vài giây. Streaming hoạt động nhưng buffering đang bật. Đặt proxy_buffering off.

bind: address already in use. Một tiến trình khác đang giữ cổng 8088. sudo ss -tlnp | grep 8088 sẽ cho biết tiến trình đó. Lỗi này cũng xảy ra nếu bạn thêm một entry ports thứ hai trong file override thay vì sửa entry gốc.

Mật khẩu đúng bị từ chối. 5 lần thử sai sẽ kích hoạt thời gian khóa 900 giây. Hãy chờ hết thời gian khóa thay vì cài đặt lại.

Mật khẩu mới trong .env không có hiệu lực. Các credential đó chỉ được áp dụng trong lần khởi tạo đầu tiên. Hãy đổi mật khẩu trong dashboard.

Agent trả lời nhưng không bao giờ chạy tool. Kiểm tra context allocation của model local và khả năng hỗ trợ function calling. Ollama hiện khuyến nghị ít nhất 64,000 token cho workload của agent. Hãy chọn model và memory budget hỗ trợ mức này.

FAQ

Octop có thay thế được Open WebUI không?

Chỉ khi bạn cần những tính năng mà Octop bổ sung. Open WebUI cũng hỗ trợ nhiều người dùng, role và quyền kiểm soát truy cập. Octop kết hợp account với role admin, workspace và credential riêng cho từng người dùng, cùng một thư viện agent chuyên biệt có thể chuyển đổi. Nhờ đó, nhiều người có thể dùng chung một server mà không dùng chung lịch sử. Nếu bạn chỉ cần một account, Open WebUI là lựa chọn đơn giản hơn và trưởng thành hơn nhiều.

Tại sao không nên dùng script cài đặt Octop qua curl?

Lệnh một dòng của v0.9.19 tải một script từ bucket Tencent Cloud Object Storage mà không cố định nội dung theo git tag hoặc commit. Repository có bản đã version tại scripts/install.sh, nhưng pipe bản remote vào bash sẽ chạy script trước khi bạn đọc nó. Script cũng cài trực tiếp lên host bằng môi trường Python 3.12 riêng, nằm ngoài package manager của bạn. Hãy tải script xuống và đọc trước, hoặc triển khai bằng Docker Compose từ một tag đã checkout.

Octop có thể dùng model local thay cho API trả phí không?

Có. Octop hỗ trợ API tương thích với OpenAI và có sẵn preset Ollama. Vì vậy, trỏ Octop đến http://host.docker.internal:11434/v1 sẽ hoạt động sau khi bạn thêm extra_hosts: ["host.docker.internal:host-gateway"] vào container và đặt OLLAMA_HOST=0.0.0.0:11434 trên host. Hãy giới hạn firewall cho port 11434 trong dải địa chỉ của Docker, vì local API của Ollama không yêu cầu xác thực. Kiểm tra context window được cấp phát. Mặc định của Ollama hiện thay đổi theo VRAM, và hướng dẫn hiện tại của Ollama khuyến nghị ít nhất 64,000 token cho workload agent, trong giới hạn context mà model hỗ trợ và bộ nhớ khả dụng.

Tôi có cần reverse proxy không, hay có thể mở port 8088?

Bạn cần reverse proxy. File Compose đi kèm Octop publish port 8088 trên mọi interface mà không có TLS. Vì vậy, password và bearer token sẽ truyền qua Internet dưới dạng plaintext. Hãy đổi port được publish thành 127.0.0.1:8088:8088 và đặt Caddy hoặc nginx phía trước cùng với certificate. Với nginx, hãy chuyển tiếp các header nâng cấp WebSocket và đặt proxy_buffering off. Nếu quá trình nâng cấp thất bại, chat sẽ không thể kết nối; còn buffering sẽ làm chậm stream resume của HITL. Trong v0.9.19, handshake thất bại sẽ kết thúc trạng thái streaming, còn disconnect không hủy một agent task đang chạy.

Octop đã sẵn sàng cho production chưa?

Tính đến tháng 8 năm 2026, Octop vẫn ở giai đoạn trước phiên bản 1.0 và phát hành nhiều tag mỗi tuần. Octop gắn tag v1.0.0 vào ngày 14 tháng 9 năm 2026, sau đó phát hành liên tiếp các tag beta 1.0.2 trước khi phát hành bản stable v1.0.2 vào ngày 18 tháng 10 năm 2026. Tính đến ngày 20 tháng 11 năm 2026, tag mới nhất là v1.0.3b7, được publish vào ngày 18 tháng 11 năm 2026, trong khi v1.0.2 vẫn là stable release mới nhất. Tốc độ phát triển vẫn rất nhanh, nên hãy xem Octop là sản phẩm có triển vọng chứ chưa thật sự ổn định. Octop có thể dùng được cho gia đình hoặc team nội bộ nhỏ nếu bạn pin một tag cụ thể, đọc commit log trước mỗi lần upgrade và backup data volume trước mỗi lần rebuild. Không chạy Octop trên latest và hiện chưa nên đưa dữ liệu khách hàng vào đó.

Bài viết này có hữu ích không?