picoclaw/cmd/picoclaw-launcher/README.zh.md

PicoClaw Launcher

Warning

该项目属于临时解决方案，后续会重构并提供完整的 Web 服务，因此该目录下的接口并不稳定。

PicoClaw 的独立启动器，提供可视化 JSON 配置编辑和 OAuth Provider 认证管理。

功能

• 📝 配置编辑 — 侧边栏式设置 UI，支持模型管理、通道配置表单和原始 JSON 编辑器
• 🤖 模型管理 — 模型卡片网格，可用性状态显示（无 API Key 时灰色），主模型选择，增删改查，必填/选填字段分离
• 📡 通道配置 — 12 种通道类型（Telegram、Discord、Slack、企业微信、钉钉、飞书、LINE、WhatsApp、QQ、OneBot、MaixCAM 等）的表单化配置，附带文档链接
• 🔐 Provider 认证 — 支持 OpenAI (Device Code)、Anthropic (API Token)、Google Antigravity (Browser OAuth) 登录
• 🌐 嵌入式前端 — 编译为单一二进制文件，无需额外依赖
• 🌍 国际化 — 中英文切换，首次访问自动检测浏览器语言
• 🎨 主题 — 亮色 / 暗色 / 跟随系统，偏好保存在 localStorage

快速开始

# 编译
go build -o picoclaw-launcher ./cmd/picoclaw-launcher/

# 运行（使用默认配置路径 ~/.picoclaw/config.json）
./picoclaw-launcher

# 指定配置文件
./picoclaw-launcher ./config.json

# 允许局域网访问
./picoclaw-launcher -public

启动后在浏览器中打开 http://localhost:18800。

命令行参数

Usage: picoclaw-launcher [options] [config.json]

Arguments:
  config.json    配置文件路径（默认: ~/.picoclaw/config.json）

Options:
  -public        监听所有网络接口（0.0.0.0），允许局域网设备访问

API 文档

Base URL: http://localhost:18800

静态文件

GET /

提供嵌入式前端页面（index.html）。

---

Config API

GET /api/config

读取当前配置文件内容。

Response 200 OK

{
  "config": { ... },
  "path": "/Users/xiao/.picoclaw/config.json"
}

---

PUT /api/config

保存配置。请求体为完整的 Config JSON。

Request Body — application/json

{
  "agents": { "defaults": { "model_name": "gpt-5.2" } },
  "model_list": [
    {
      "model_name": "gpt-5.2",
      "model": "openai/gpt-5.2",
      "auth_method": "oauth"
    }
  ]
}

Response 200 OK

{ "status": "ok" }

Error 400 Bad Request — 无效 JSON

---

Auth API

GET /api/auth/status

获取所有 Provider 的认证状态和进行中的 Device Code 登录信息。

Response 200 OK

{
  "providers": [
    {
      "provider": "openai",
      "auth_method": "oauth",
      "status": "active",
      "account_id": "user-xxx",
      "expires_at": "2026-03-01T00:00:00Z"
    }
  ],
  "pending_device": {
    "provider": "openai",
    "status": "pending",
    "device_url": "https://auth.openai.com/activate",
    "user_code": "ABCD-1234"
  }
}

status 可选值: active | expired | needs_refresh

pending_device 仅在有进行中的 Device Code 登录时返回。

---

POST /api/auth/login

发起 Provider 登录。

Request Body — application/json

{ "provider": "openai" }

支持的 provider 值: openai | anthropic | google-antigravity

OpenAI (Device Code Flow)

返回 Device Code 信息，后台自动轮询认证结果：

{
  "status": "pending",
  "device_url": "https://auth.openai.com/activate",
  "user_code": "ABCD-1234",
  "message": "Open the URL and enter the code to authenticate."
}

用户在浏览器中打开 device_url 并输入 user_code。认证完成后通过 GET /api/auth/status 的 pending_device.status 变为 success 通知前端。

Anthropic (API Token)

需在请求中附带 token：

{ "provider": "anthropic", "token": "sk-ant-xxx" }

Response:

{ "status": "success", "message": "Anthropic token saved" }

Google Antigravity (Browser OAuth)

返回授权 URL，前端打开新标签页：

{
  "status": "redirect",
  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
  "message": "Open the URL to authenticate with Google."
}

认证完成后 Google 回调至 GET /auth/callback，自动保存凭据并重定向回 picoclaw-config 页面。

---

POST /api/auth/logout

登出 Provider。

Request Body — application/json

{ "provider": "openai" }

传空字符串或省略 provider 则登出所有 Provider。

Response 200 OK

{ "status": "ok" }

---

GET /auth/callback

OAuth Browser 回调端点（Google Antigravity 专用），由 OAuth Provider 重定向调用，非前端直接使用。

Query Parameters:

• state — OAuth state 校验
• code — 授权码

认证成功后重定向到 /#auth。

Process API

GET /api/process/status

获取 picoclaw gateway 进程的运行状态。

Response 200 OK (运行中)

{
  "process_status": "running",
  "status": "ok",
  "uptime": "1.010814s"
}

Response 200 OK (未运行)

{
  "process_status": "stopped",
  "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
}

---

POST /api/process/start

在后台启动 picoclaw gateway 进程。

Response 200 OK

{
  "status": "ok",
  "pid": 12345
}

---

POST /api/process/stop

停止正在运行的 picoclaw gateway 进程。

Response 200 OK

{
  "status": "ok"
}

---

测试

go test -v ./cmd/picoclaw-launcher/