picoclaw/docs/guides/docker.vi.md

🐳 Docker và Bắt Đầu Nhanh

Quay lại README

🐳 Docker Compose

Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cài đặt gì trên máy.

# 1. Clone repo này
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# 2. Lần chạy đầu tiên — tự động tạo docker/data/config.json rồi thoát
#    (chỉ kích hoạt khi cả config.json và workspace/ đều không tồn tại)
docker compose -f docker/docker-compose.yml --profile gateway up
# Container hiển thị "First-run setup complete." và dừng lại.

# 3. Cấu hình API key của bạn
vim docker/data/config.json   # Set provider API keys, bot tokens, etc.

# 4. Khởi động
docker compose -f docker/docker-compose.yml --profile gateway up -d

Tip

Người dùng Docker: Mặc định, Gateway lắng nghe trên 127.0.0.1, không thể truy cập từ host. Nếu bạn cần truy cập các health endpoint hoặc mở port, hãy đặt PICOCLAW_GATEWAY_HOST=0.0.0.0 trong môi trường hoặc cập nhật config.json.

# 5. Kiểm tra log
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

# 6. Dừng
docker compose -f docker/docker-compose.yml --profile gateway down

Chế Độ Launcher (Web Console)

Image launcher bao gồm cả ba binary (picoclaw, picoclaw-launcher, picoclaw-launcher-tui) và khởi động web console mặc định, cung cấp giao diện trình duyệt để cấu hình và chat.

docker compose -f docker/docker-compose.yml --profile launcher up -d

Mở http://localhost:18800 trong trình duyệt. Launcher tự động quản lý tiến trình gateway.

Warning

Web console được bảo vệ bằng mật khẩu đăng nhập dashboard. Không để lộ launcher ra mạng không tin cậy hoặc internet công cộng.

Chế Độ Agent (One-shot)

# Đặt câu hỏi
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"

# Chế độ tương tác
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent

Cập Nhật

docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml --profile gateway up -d

🚀 Bắt Đầu Nhanh

Tip

Cấu hình API Key trong ~/.picoclaw/config.json. Lấy API Key: Volcengine (CodingPlan) (LLM) · OpenRouter (LLM) · Zhipu (LLM). Tìm kiếm web là tùy chọn — lấy miễn phí Tavily API (1000 truy vấn miễn phí/tháng) hoặc Brave Search API (2000 truy vấn miễn phí/tháng).

1. Khởi tạo

picoclaw onboard

2. Cấu hình (~/.picoclaw/config.json)

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt-5.4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "model_list": [
    {
      "model_name": "ark-code-latest",
      "model": "volcengine/ark-code-latest",
      "api_keys": ["sk-your-api-key"],
      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_keys": ["your-api-key"],
      "request_timeout": 300
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_keys": ["your-anthropic-key"]
    }
  ],
  "tools": {
    "web": {
      "enabled": true,
      "fetch_limit_bytes": 10485760,
      "format": "plaintext",
      "brave": {
        "enabled": false,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "tavily": {
        "enabled": false,
        "api_key": "YOUR_TAVILY_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "YOUR_PERPLEXITY_API_KEY",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://your-searxng-instance:8888",
        "max_results": 5
      }
    }
  }
}

Mới: Định dạng cấu hình model_list cho phép thêm provider mà không cần thay đổi code. Xem Cấu Hình Mô Hình để biết chi tiết. request_timeout là tùy chọn và tính bằng giây. Nếu bỏ qua hoặc đặt <= 0, PicoClaw sử dụng timeout mặc định (120s).

3. Lấy API Key

• Nhà cung cấp LLM: OpenRouter · Zhipu · Anthropic · OpenAI · Gemini
• Tìm kiếm Web (tùy chọn):
  • Brave Search - Trả phí ($5/1000 truy vấn, ~$5-6/tháng)
  • Perplexity - Tìm kiếm bằng AI với giao diện chat
  • SearXNG - Công cụ tìm kiếm tổng hợp tự host (miễn phí, không cần API key)
  • Tavily - Tối ưu cho AI Agent (1000 yêu cầu/tháng)
  • DuckDuckGo - Fallback tích hợp (không cần API key)

Lưu ý: Xem config.example.json để có mẫu cấu hình đầy đủ.

4. Chat

picoclaw agent -m "What is 2+2?"

Vậy là xong! Bạn có một trợ lý AI hoạt động trong 2 phút.

---