picoclaw/docs/guides/docker.zh.md

🐳 Docker 与快速开始

返回 README

🐳 Docker Compose

您也可以使用 Docker Compose 运行 PicoClaw，无需在本地安装任何环境。

# 1. 克隆仓库
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
#    （仅在 config.json 和 workspace/ 都不存在时触发）
docker compose -f docker/docker-compose.yml --profile gateway up
# 容器打印 "First-run setup complete." 后自动停止

# 3. 填写 API Key 等配置
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。

# 5. 查看日志
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

# 6. 停止
docker compose -f docker/docker-compose.yml --profile gateway down

Launcher 模式 (Web 控制台)

launcher 镜像包含两个二进制文件（picoclaw、picoclaw-launcher），默认启动 Web 控制台，提供基于浏览器的配置和聊天界面。

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

在浏览器中打开 http://localhost:18800。Launcher 会自动管理 Gateway 进程。

Warning

Web 控制台通过 dashboard 登录密码保护。不要将启动器暴露到不可信网络或公网。完整说明见 配置指南 中的「Web 启动器控制台」一节。

Agent 模式 (一次性运行)

# 提问
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"

# 交互模式
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent

更新镜像

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

---

🚀 快速开始

Tip

在 ~/.picoclaw/config.json 中设置您的 API Key。获取 API Key: 火山引擎 (CodingPlan) (LLM) · OpenRouter (LLM) · Zhipu (智谱) (LLM)。网络搜索是 可选的 — 获取免费的 Tavily API (每月 1000 次免费查询) 或 Brave Search API (每月 2000 次免费查询)。

1. 初始化 (Initialize)

picoclaw onboard

2. 配置 (Configure) (~/.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",
      "provider": "volcengine",
      "model": "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",
      "provider": "openai",
      "model": "gpt-5.4",
      "api_keys": ["your-api-key"],
      "request_timeout": 300
    },
    {
      "model_name": "claude-sonnet-4.6",
      "provider": "anthropic",
      "model": "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
      }
    }
  }
}

新功能: model_list 配置格式支持零代码添加 provider。详见模型配置章节。 request_timeout 为可选项，单位为秒。若省略或设置为 <= 0，PicoClaw 使用默认超时（120 秒）。

3. 获取 API Key

• LLM 提供商: OpenRouter · Zhipu · Anthropic · OpenAI · Gemini
• 网络搜索 (可选):
  • Brave Search - 付费 ($5/1000 次查询，约 $5-6/月)
  • Perplexity - AI 驱动的搜索与聊天界面
  • SearXNG - 自建元搜索引擎（免费，无需 API Key）
  • Tavily - 专为 AI Agent 优化 (1000 请求/月)
  • DuckDuckGo - 内置回退（无需 API Key）

注意: 完整的配置模板请参考 config.example.json。

4. 对话 (Chat)

picoclaw agent -m "2+2 等于几？"

就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。

---