chore(docker): reorganize docker files and add first-run entrypoint (#812)

* chore(docker): move Dockerfile into docker/ directory

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(docker): add entrypoint script to goreleaser Dockerfile

- entrypoint.sh: on first run (config and workspace both absent) runs
  picoclaw onboard then exits for the user to configure; subsequent
  starts exec picoclaw gateway directly
- Dockerfile.goreleaser: copy and use entrypoint.sh, run as root
- .goreleaser.yaml: update dockerfile path, add entrypoint.sh to
  extra_files so it is included in the docker build context

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore(docker): update docker-compose to use pre-built image and bind mount

- Use docker.io/sipeed/picoclaw:latest instead of building locally
- Replace named volume with bind mount ./data:/root/.picoclaw
- Move docker-compose.yml into docker/ directory

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: update Docker Compose section to reflect new docker/ layout

- Use docker compose -f docker/docker-compose.yml for all commands
- Update setup flow: first run generates docker/data/config.json,
  container exits, user edits config, then restarts
- Replace "Rebuild" section with "Update" (docker pull) since the
  compose file now uses the pre-built sipeed/picoclaw image
- Apply same changes to README.zh.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(docker): use restart: on-failure to prevent restart after first-run setup

unless-stopped restarts the container regardless of exit code, causing
an infinite loop when entrypoint exits 0 after the initial onboard.
on-failure only restarts on non-zero exit (i.e. crashes), so the
container stays stopped after setup until the user restarts it manually.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs: sync Docker Compose section across all language READMEs

Apply the same updates as the English/Chinese READMEs:
- Use docker compose -f docker/docker-compose.yml for all commands
- Update setup flow to first-run auto-config pattern
- Replace build/rebuild section with update via docker pull
- Affected: README.fr.md, README.ja.md, README.pt-br.md, README.vi.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

.goreleaser.yaml

@@ -39,7 +39,9 @@ builds:
 
 dockers_v2:
   - id: picoclaw
-    dockerfile: Dockerfile.goreleaser
+    dockerfile: docker/Dockerfile.goreleaser
+    extra_files:
+      - docker/entrypoint.sh
     ids:
       - picoclaw
     images:

README.fr.md

@@ -164,39 +164,43 @@ Vous pouvez également exécuter PicoClaw avec Docker Compose sans rien installe
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Configurez vos clés API
+# 2. Premier lancement — génère docker/data/config.json puis s'arrête
-cp config/config.example.json config/config.json
+docker compose -f docker/docker-compose.yml --profile gateway up
-vim config/config.json      # Configurez DISCORD_BOT_TOKEN, clés API, etc.
+# Le conteneur affiche "First-run setup complete." puis s'arrête.
 
-# 3. Compiler & Démarrer
+# 3. Configurez vos clés API
-docker compose --profile gateway up -d
+vim docker/data/config.json   # Clés API du fournisseur, tokens de bot, etc.
+
+# 4. Démarrer
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!TIP]
 > **Utilisateurs Docker** : Par défaut, le Gateway écoute sur `127.0.0.1`, ce qui n'est pas accessible depuis l'hôte. Si vous avez besoin d'accéder aux endpoints de santé ou d'exposer des ports, définissez `PICOCLAW_GATEWAY_HOST=0.0.0.0` dans votre environnement ou mettez à jour `config.json`.
 
+```bash
+# 5. Voir les logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. Voir les logs
+# 6. Arrêter
-docker compose logs -f picoclaw-gateway
+docker compose -f docker/docker-compose.yml --profile gateway down
-
-# 5. Arrêter
-docker compose --profile gateway down
 ```
 
 ### Mode Agent (exécution unique)
 
 ```bash
 # Poser une question
-docker compose run --rm picoclaw-agent -m "Combien font 2+2 ?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Combien font 2+2 ?"
 
 # Mode interactif
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Recompiler
+### Mettre à jour
 
 ```bash
-docker compose --profile gateway build --no-cache
+docker compose -f docker/docker-compose.yml pull
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Démarrage Rapide

README.ja.md

@@ -126,39 +126,43 @@ Docker Compose を使えば、ローカルにインストールせずに PicoCla
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. API キーを設定
+# 2. 初回起動 — docker/data/config.json を自動生成して終了
-cp config/config.example.json config/config.json
+docker compose -f docker/docker-compose.yml --profile gateway up
-vim config/config.json      # DISCORD_BOT_TOKEN, プロバイダーの API キーを設定
+# コンテナが "First-run setup complete." を表示して停止します。
 
-# 3. ビルドと起動
+# 3. API キーを設定
-docker compose --profile gateway up -d
+vim docker/data/config.json   # プロバイダー API キー、Bot トークンなどを設定
+
+# 4. 起動
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!TIP]
 > **Docker ユーザー**: デフォルトでは、Gateway は `127.0.0.1` でリッスンしており、ホストからアクセスできません。ヘルスチェックエンドポイントにアクセスしたり、ポートを公開したりする必要がある場合は、環境変数で `PICOCLAW_GATEWAY_HOST=0.0.0.0` を設定するか、`config.json` を更新してください。
 
+```bash
+# 5. ログ確認
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. ログ確認
+# 6. 停止
-docker compose logs -f picoclaw-gateway
+docker compose -f docker/docker-compose.yml --profile gateway down
-
-# 5. 停止
-docker compose --profile gateway down
 ```
 
 ### Agent モード（ワンショット）
 
 ```bash
 # 質問を投げる
-docker compose run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
 
 # インタラクティブモード
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### リビルド
+### アップデート
 
 ```bash
-docker compose --profile gateway build --no-cache
+docker compose -f docker/docker-compose.yml pull
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 クイックスタート（ネイティブ）

README.md

@@ -167,39 +167,43 @@ You can also run PicoClaw using Docker Compose without installing anything local
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Set your API keys
+# 2. First run — auto-generates docker/data/config.json then exits
-cp config/config.example.json config/config.json
+docker compose -f docker/docker-compose.yml --profile gateway up
-vim config/config.json      # Set DISCORD_BOT_TOKEN, API keys, etc.
+# The container prints "First-run setup complete." and stops.
 
-# 3. Build & Start
+# 3. Set your API keys
-docker compose --profile gateway up -d
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 4. Start
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!TIP]
 > **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
 
+```bash
+# 5. Check logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. Check logs
+# 6. Stop
-docker compose logs -f picoclaw-gateway
+docker compose -f docker/docker-compose.yml --profile gateway down
-
-# 5. Stop
-docker compose --profile gateway down
 ```
 
 ### Agent Mode (One-shot)
 
 ```bash
 # Ask a question
-docker compose run --rm picoclaw-agent -m "What is 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
 
 # Interactive mode
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Rebuild
+### Update
 
 ```bash
-docker compose --profile gateway build --no-cache
+docker compose -f docker/docker-compose.yml pull
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Quick Start

README.pt-br.md

@@ -165,39 +165,43 @@ Você tambêm pode rodar o PicoClaw usando Docker Compose sem instalar nada loca
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Configure suas API keys
+# 2. Primeiro uso — gera docker/data/config.json automaticamente e para
-cp config/config.example.json config/config.json
+docker compose -f docker/docker-compose.yml --profile gateway up
-vim config/config.json      # Configure DISCORD_BOT_TOKEN, API keys, etc.
+# O contêiner exibe "First-run setup complete." e para.
 
-# 3. Build & Iniciar
+# 3. Configure suas API keys
-docker compose --profile gateway up -d
+vim docker/data/config.json   # Chaves de API do provedor, tokens de bot, etc.
+
+# 4. Iniciar
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!TIP]
 > **Usuários Docker**: Por padrão, o Gateway ouve em `127.0.0.1`, o que não é acessível a partir do host. Se você precisar acessar os endpoints de integridade ou expor portas, defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` em seu ambiente ou atualize o `config.json`.
 
+```bash
+# 5. Ver logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. Ver logs
+# 6. Parar
-docker compose logs -f picoclaw-gateway
+docker compose -f docker/docker-compose.yml --profile gateway down
-
-# 5. Parar
-docker compose --profile gateway down
 ```
 
 ### Modo Agente (Execução única)
 
 ```bash
 # Fazer uma pergunta
-docker compose run --rm picoclaw-agent -m "Quanto e 2+2?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Quanto e 2+2?"
 
 # Modo interativo
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Rebuild
+### Atualizar
 
 ```bash
-docker compose --profile gateway build --no-cache
+docker compose -f docker/docker-compose.yml pull
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Início Rápido

README.vi.md

@@ -145,39 +145,43 @@ Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cà
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Thiết lập API Key
+# 2. Lần chạy đầu tiên — tự tạo docker/data/config.json rồi dừng lại
-cp config/config.example.json config/config.json
+docker compose -f docker/docker-compose.yml --profile gateway up
-vim config/config.json      # Thiết lập DISCORD_BOT_TOKEN, API keys, v.v.
+# Container hiển thị "First-run setup complete." rồi tự dừng.
 
-# 3. Build & Khởi động
+# 3. Thiết lập API Key
-docker compose --profile gateway up -d
+vim docker/data/config.json   # API key của provider, bot token, v.v.
+
+# 4. Khởi động
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!TIP]
 > **Người dùng Docker**: Theo mặc định, Gateway lắng nghe trên `127.0.0.1`, không thể truy cập từ máy chủ. Nếu bạn cần truy cập các endpoint kiểm tra sức khỏe hoặc mở cổng, hãy đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` trong môi trường của bạn hoặc cập nhật `config.json`.
 
+```bash
+# 5. Xem logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
 
-# 4. Xem logs
+# 6. Dừng
-docker compose logs -f picoclaw-gateway
+docker compose -f docker/docker-compose.yml --profile gateway down
-
-# 5. Dừng
-docker compose --profile gateway down
 ```
 
 ### Chế độ Agent (chạy một lần)
 
 ```bash
 # Đặt câu hỏi
-docker compose run --rm picoclaw-agent -m "2+2 bằng mấy?"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 bằng mấy?"
 
 # Chế độ tương tác
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
 ```
 
-### Build lại
+### Cập nhật
 
 ```bash
-docker compose --profile gateway build --no-cache
+docker compose -f docker/docker-compose.yml pull
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile gateway up -d
 ```
 
 ### 🚀 Bắt đầu nhanh

README.zh.md

@@ -166,41 +166,43 @@ make install
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. 设置 API Key
+# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
-cp config/config.example.json config/config.json
+docker compose -f docker/docker-compose.yml --profile gateway up
-vim config/config.json      # 设置 DISCORD_BOT_TOKEN, API keys 等
+# 容器打印 "First-run setup complete." 后自动停止
 
-# 3. 构建并启动
+# 3. 填写 API Key 等配置
-docker compose --profile gateway up -d
+vim docker/data/config.json   # 设置 provider API key、Bot Token 等
+
+# 4. 正式启动
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
 
 > [!TIP]
-**Docker 用户**: 默认情况下, Gateway监听 `127.0.0.1`，这使得这个端口未暴露到容器外。如果你需要通过端口映射访问健康检查接口, 请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
+> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
 
-# 4. 查看日志
+```bash
-docker compose logs -f picoclaw-gateway
+# 5. 查看日志
-
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
-# 5. 停止
-docker compose --profile gateway down
 
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
 ```
 
 ### Agent 模式 (一次性运行)
 
 ```bash
 # 提问
-docker compose run --rm picoclaw-agent -m "2+2 等于几？"
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
 
 # 交互模式
-docker compose run --rm picoclaw-agent
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-
 ```
 
-### 重新构建
+### 更新镜像
 
 ```bash
-docker compose --profile gateway build --no-cache
+docker compose -f docker/docker-compose.yml pull
-docker compose --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile gateway up -d
-
 ```
 
 ### 🚀 快速开始

docker/Dockerfile.goreleaser

@@ -5,6 +5,8 @@ ARG TARGETPLATFORM
 RUN apk add --no-cache ca-certificates tzdata
 
 COPY $TARGETPLATFORM/picoclaw /usr/local/bin/picoclaw
+COPY docker/entrypoint.sh /entrypoint.sh
 
-ENTRYPOINT ["picoclaw"]
+RUN chmod +x /entrypoint.sh
-CMD ["gateway"]
+
+ENTRYPOINT ["/entrypoint.sh"]

docker/docker-compose.yml

@@ -1,12 +1,10 @@
 services:
   # ─────────────────────────────────────────────
   # PicoClaw Agent (one-shot query)
-  #   docker compose run --rm picoclaw-agent -m "Hello"
+  #   docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Hello"
   # ─────────────────────────────────────────────
   picoclaw-agent:
-    build:
+    image: docker.io/sipeed/picoclaw:latest
-      context: .
-      dockerfile: Dockerfile
     container_name: picoclaw-agent
     profiles:
       - agent
@@ -14,33 +12,23 @@ services:
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
+      - ./data:/root/.picoclaw
-      - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
     entrypoint: ["picoclaw", "agent"]
     stdin_open: true
     tty: true
 
   # ─────────────────────────────────────────────
   # PicoClaw Gateway (Long-running Bot)
-  #   docker compose up picoclaw-gateway
+  #   docker compose -f docker/docker-compose.yml up picoclaw-gateway
   # ─────────────────────────────────────────────
   picoclaw-gateway:
-    build:
+    image: docker.io/sipeed/picoclaw:latest
-      context: .
-      dockerfile: Dockerfile
     container_name: picoclaw-gateway
-    restart: unless-stopped
+    restart: on-failure
     profiles:
       - gateway
     # Uncomment to access host network; leave commented unless needed.
     #extra_hosts:
     #  - "host.docker.internal:host-gateway"
     volumes:
-      # Configuration file
+      - ./data:/root/.picoclaw
-      - ./config/config.json:/home/picoclaw/.picoclaw/config.json:ro
-      # Persistent workspace (sessions, memory, logs)
-      - picoclaw-workspace:/home/picoclaw/.picoclaw/workspace
-    command: ["gateway"]
-
-volumes:
-  picoclaw-workspace:

docker/entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+set -e
+
+# First-run: neither config nor workspace exists.
+# If config.json is already mounted but workspace is missing we skip onboard to
+# avoid the interactive "Overwrite? (y/n)" prompt hanging in a non-TTY container.
+if [ ! -d "${HOME}/.picoclaw/workspace" ] && [ ! -f "${HOME}/.picoclaw/config.json" ]; then
+    picoclaw onboard
+    echo ""
+    echo "First-run setup complete."
+    echo "Edit ${HOME}/.picoclaw/config.json (add your API key, etc.) then restart the container."
+    exit 0
+fi
+
+exec picoclaw gateway "$@"