PicoClaw Docker 部署实战指南：用 Docker Compose 快速跑起 AI Agent、Gateway 与 Web 控制台

人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载本文档基于仓库内 docs/guides/docker.vi.md 编写并辅以 docker/docker-compose.yml、docker/entrypoint.sh、docker/Dockerfile 等源码级证据。PicoClaw 是一个轻量级的个人 AI 助手官方仓库内置了完整的 Docker 部署方案无需在宿主机安装任何运行时依赖通过docker compose即可在几分钟内启动三种运行模式——常驻Gateway长驻机器人、LauncherWeb 控制台与一次性Agent单次问答。读完本文你将掌握 PicoClaw 的 Docker Compose 全流程操作首次运行自动初始化配置、三种 profile 的启动/停止/查日志命令、config.json的模型与工具配置以及镜像更新的标准流程。一、Docker Compose 总览三种服务、三个 profile仓库根目录下的 docker/docker-compose.yml 定义了三个服务分别对应三种运行模式通过 Compose 的--profile参数按需启用服务名profile用途入口picoclaw-agentagent一次性问答one-shot适合脚本化调用picoclaw agentpicoclaw-gatewaygateway长驻机器人进程处理各渠道 Webhook 与健康检查/entrypoint.sh→picoclaw gatewaypicoclaw-launcherlauncherWeb 控制台浏览器配置 聊天自动管理 gatewaypicoclaw-launcher三个服务都将宿主机目录./data挂载为容器内的/root/.picoclawdocker/docker-compose.yml也就是说你的配置、workspace、会话与日志都会持久化保存在仓库目录下的docker/data/中容器删除后数据不丢失。# 克隆仓库如尚未克隆 git clone https://github.com/sipeed/picoclaw.git cd picoclaw注意gatewayprofile 只提供 Webhook 处理包括启用 Pico 渠道时的/pico/ws和健康检查端点不会暴露/chat、/a2a之类的通用 REST 聊天接口而 launcher 模式会额外提供浏览器 UI、/api/pico/info以及带鉴权的/pico/ws代理。若需要在网关端口直接访问/pico/ws启用 Pico 渠道即可。二、Gateway 模式首次运行自动初始化2.1 首次运行生成配置后自动退出# 首次运行自动生成 docker/data/config.json 后退出 # 仅当 config.json 与 workspace/ 均不存在时触发 docker compose -f docker/docker-compose.yml --profile gateway up # 容器打印 First-run setup complete. 并停止这一步背后是 docker/entrypoint.sh 的首次运行逻辑当~/.picoclaw/workspace目录与~/.picoclaw/config.json文件同时缺失时脚本执行picoclaw onboard生成默认配置随后打印First-run setup complete.并exit 0。注释里特别说明了一个坑如果config.json已挂载但 workspace 缺失脚本会跳过onboard以避免交互式 Overwrite? (y/n) 提示在无 TTY 的容器中挂起。2.2 写入 API Key 并正式启动# 编辑生成的配置文件填入 provider 的 API key、bot token 等 vim docker/data/config.json # 正式以后台守护方式启动 docker compose -f docker/docker-compose.yml --profile gateway up -d[!TIP]Docker 用户须知默认情况下 Gateway 监听127.0.0.1宿主机无法直接访问。如果你需要访问健康检查端点或对外暴露端口请在环境变量中设置PICOCLAW_GATEWAY_HOST0.0.0.0或直接修改config.json中的gateway.host。这一点在源码中有明确印证pkg/config/gateway.go 中gateway.host字段标注了env:PICOCLAW_GATEWAY_HOSTpkg/config/envkeys.go 定义了该环境变量名。默认网关端口为18790见 config/config.example.jsonDockerfile 中的健康检查正是探测http://localhost:18790/healthdocker/Dockerfile。2.3 查看日志与停止# 查看 gateway 容器日志-f 跟随输出 docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway # 停止并移除容器 docker compose -f docker/docker-compose.yml --profile gateway down注意docker-compose.yml中picoclaw-gateway设置了restart: unless-stopped容器异常退出如 OOM、docker kill后会自动重启。entrypoint.sh 在每次启动前会清理可能残留的 PID 文件~/.picoclaw/.picoclaw.pid避免上次崩溃遗留的 PID 与容器内新进程冲突导致 gateway 启动失败。三、Launcher 模式Web 控制台launcher镜像同时包含两个二进制picoclaw与picoclaw-launcher默认启动 Web 控制台提供基于浏览器的配置与聊天界面。docker compose -f docker/docker-compose.yml --profile launcher up -d然后在浏览器打开http://localhost:18800。Launcher 会自动管理 gateway 进程——控制台界面上点击 Start Gateway 即可拉起后端服务开始聊天。从 docker/docker-compose.yml 可以看到 launcher 服务的三个关键配置端口映射18800Web 控制台与18790网关端口同时映射到宿主机PICOCLAW_GATEWAY_HOST0.0.0.0launcher 镜像内已默认让 gateway 监听所有网卡便于容器内联调PICOCLAW_LAUNCHER_TOKEN注释中如果不设置每次重启会随机生成一个 token 并打印到控制台设置固定值可避免反复变更。dashboard 登录密码保护整个控制台。[!WARNING] Web 控制台由 dashboard 登录密码保护。切勿将 launcher 暴露到不受信任的网络或公网更详细的 dashboard 安全说明可参考 configuration.md 的 Web Launcher Dashboard 一节。launcher镜像的构建细节见 docker/Dockerfile.launcher先用 Node.js pnpm 构建前端web/frontend→web/backend/dist内嵌再用 Go 编译picoclaw与picoclaw-launcher两个二进制最终运行参数为picoclaw-launcher -console -public -no-browser即启动控制台、允许局域网访问但不自动打开浏览器。四、Agent 模式一次性问答适合写脚本、跑 CI 或快速验证配置的agentprofile# 单次提问直接问 What is 22? docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m What is 22? # 交互式模式进入 REPL可连续对话 docker compose -f docker/docker-compose.yml run --rm picoclaw-agentrun --rm表示用完即删容器picoclaw-agent服务的 entrypoint 为picoclaw agentdocker/docker-compose.yml并开启了stdin_open: true与tty: true以支持交互输入。五、镜像更新# 拉取最新镜像 docker compose -f docker/docker-compose.yml pull # 用新镜像重建并后台启动 gateway docker compose -f docker/docker-compose.yml --profile gateway up -d由于./data数据卷是持久化的升级镜像不会丢失配置与历史数据。up -d会自动用新镜像重建已存在的容器。六、快速上手Quick Start从 onboard 到第一次对话除了 DockerPicoClaw 也支持直接运行二进制快速体验。以下流程同样适用于容器内entrypoint 首次运行做的就是第 1 步。6.1 初始化picoclaw onboard该命令会在~/.picoclaw/下生成默认的config.json与workspace/目录并引导你完成基础配置。6.2 配置config.json编辑~/.picoclaw/config.json一个典型的最小可用配置如下来自 docs/guides/docker.vi.md 原文{ 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 } } } }关键字段说明agents.defaults全局 Agent 默认参数。workspace为工作区目录限定 Agent 的文件读写范围model_name默认模型max_tokens单次回复最大 token 数temperature采样温度max_tool_iterations单轮最多工具调用迭代次数。model_list新格式允许零代码添加 provider无需改动程序即可接入任意模型。数组中的model_name是你在配置中引用的别名model是provider/模型ID格式的完整标识api_keys支持传入多个 key多 key 场景下 PicoClaw 会自动做负载均衡与故障回退见 config/config.example.json 的 loadbalanced 示例。request_timeout可选单位为秒。如果省略或设为 0PicoClaw 使用默认超时120 秒。tools.web联网搜索工具配置。enabled总开关fetch_limit_bytes限制抓取网页正文的最大字节数默认 10MBformat输出格式下方各子模块Brave / Tavily / DuckDuckGo / Perplexity / SearXNG可分别启用并设置api_key与max_results。其中 DuckDuckGo 为内置 fallback无需任何 API key。需要更完整的配置模板含全部渠道、MCP、hooks、gateway 等选项时请直接参考仓库根目录的 config/config.example.json其中有详细的注释与默认值。6.3 获取 API KeyLLM ProviderOpenRouter、智谱Zhipu、Anthropic、OpenAI、Gemini、火山方舟Volcengine CodingPlan等各平台申请对应 key 填入api_keys。Web 搜索可选Brave Search付费约 $5/1000 次查询、Tavily面向 AI Agent 优化免费额度 1000 次/月、Perplexity带聊天界面的 AI 搜索、SearXNG自托管元搜索引擎免费无需 key、DuckDuckGo内置 fallback免 key。6.4 开始对话picoclaw agent -m What is 22?搞定不到 2 分钟你就拥有一个可用的 AI 助手了。七、进阶带完整 MCP 支持的镜像可选如果 Agent 需要运行基于 Node.js/npm 的 MCP 服务器如官方示例中的modelcontextprotocol/server-*系列基础镜像不包含 Node 运行时。仓库另外提供了全功能镜像docker/Dockerfile.full在基础镜像上叠加 Node.js/npm 环境docker/docker-compose.full.yml对应的 Compose 编排将config/config.json以只读方式挂载并用命名卷picoclaw-workspace持久化 workspace、用picoclaw-npm-cache缓存 npm 包以加速 MCP server 的重复安装。# 带完整 MCP 支持的一次性问答 docker compose -f docker/docker-compose.full.yml run --rm picoclaw-agent -m Hello # 带完整 MCP 支持的常驻网关 docker compose -f docker/docker-compose.full.yml --profile gateway up -d按需选择普通场景用基础镜像更轻量需要 MCP 生态时切换到full版本即可配置文件与 workspace 的使用方式完全一致。赞分享人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载相关推荐PicoClaw Docker 部署与快速上手指南Compose 三种模式、Launcher Web 控制台与模型配置实战PicoClaw Docker 部署与快速上手指南Compose 三种模式、Launcher Web 控制台与模型配置实战 本篇指南完整讲解如何在零本地依赖的人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆PicoClaw Docker 部署与快速开始完全指南Compose、Launcher 与 Agent 三种模式实战PicoClaw Docker 部署与快速开始完全指南Compose、Launcher 与 Agent 三种模式实战 本文面向希望在任意机器上快速体验 Pic人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆PicoClaw 容器化部署实战Docker Compose 三种模式、Launcher Web 控制台与配置详解PicoClaw 容器化部署实战Docker Compose 三种模式、Launcher Web 控制台与配置详解 PicoClaw 是一个「小而快、随处可部人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆上一篇Boost.Beast中的WebSocket超时机制详解下一篇Garak项目大语言模型安全检测工具深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考