{"id":45700900,"url":"https://github.com/qingchencloud/clawapp","last_synced_at":"2026-03-08T07:10:17.131Z","repository":{"id":338942020,"uuid":"1159447451","full_name":"qingchencloud/clawapp","owner":"qingchencloud","description":"📱 ClawApp — Mobile H5 chat client for OpenClaw AI Agent platform. 用手机和你的 AI 智能体聊天。","archived":false,"fork":false,"pushed_at":"2026-02-24T16:33:49.000Z","size":1930,"stargazers_count":80,"open_issues_count":1,"forks_count":10,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-25T00:30:35.807Z","etag":null,"topics":["ai-agents","ai-assistant","android","capacitor","chat-client","chinese","dark-mode","h5","i18n","markdown","mobile-chat","openclaw","pwa","self-hosted","streaming","websocket"],"latest_commit_sha":null,"homepage":"https://clawapp.qt.cool/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qingchencloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T18:34:43.000Z","updated_at":"2026-02-24T16:35:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/qingchencloud/clawapp","commit_stats":null,"previous_names":["qingchencloud/clawapp"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/qingchencloud/clawapp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fclawapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fclawapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fclawapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fclawapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qingchencloud","download_url":"https://codeload.github.com/qingchencloud/clawapp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qingchencloud%2Fclawapp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29965419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T06:55:38.174Z","status":"ssl_error","status_checked_at":"2026-03-01T06:53:04.810Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-assistant","android","capacitor","chat-client","chinese","dark-mode","h5","i18n","markdown","mobile-chat","openclaw","pwa","self-hosted","streaming","websocket"],"created_at":"2026-02-24T22:09:27.543Z","updated_at":"2026-03-08T07:10:17.111Z","avatar_url":"https://github.com/qingchencloud.png","language":"JavaScript","funding_links":[],"categories":["Integrations \u0026 Features","AI Agent Frameworks"],"sub_categories":["Companion Apps","OpenClaw Infrastructure"],"readme":"# ClawApp\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e📱 用手机浏览器和你的 OpenClaw AI 智能体聊天\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#features\"\u003e功能特性\u003c/a\u003e •\n  \u003ca href=\"#screenshots\"\u003e截图预览\u003c/a\u003e •\n  \u003ca href=\"#quickstart\"\u003e快速开始\u003c/a\u003e •\n  \u003ca href=\"#deploy\"\u003e部署方式\u003c/a\u003e •\n  \u003ca href=\"#remote\"\u003e外网访问\u003c/a\u003e •\n  \u003ca href=\"#config\"\u003e配置参数\u003c/a\u003e •\n  \u003ca href=\"#faq\"\u003e常见问题\u003c/a\u003e •\n  \u003ca href=\"#community\"\u003e社区交流\u003c/a\u003e •\n  \u003ca href=\"#english\"\u003eEnglish\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://clawapp.qt.cool\"\u003e🌐 产品主页\u003c/a\u003e •\n  \u003ca href=\"https://github.com/1186258278/OpenClawChineseTranslation\"\u003e🇨🇳 OpenClaw 中文汉化版\u003c/a\u003e •\n  \u003ca href=\"https://discord.gg/U9AttmsNHh\"\u003e💬 Discord\u003c/a\u003e •\n  \u003ca href=\"https://yb.tencent.com/gp/i/LsvIw7mdR7Lb\"\u003e🤖 元宝派\u003c/a\u003e •\n  \u003ca href=\"https://qt.cool/c/OpenClaw\"\u003e💬 QQ 群\u003c/a\u003e •\n  \u003ca href=\"https://qt.cool/c/OpenClawWx\"\u003e💬 微信群\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e 🦀 **[ClawPanel](https://github.com/qingchencloud/clawpanel)** — 内置 AI 助手的 OpenClaw 可视化管理面板（桌面端） | 🇨🇳 **[OpenClaw 汉化版](https://github.com/1186258278/OpenClawChineseTranslation)** — 全中文 CLI + Dashboard\n\n---\n\n\u003ch2 id=\"about\"\u003e这是什么？\u003c/h2\u003e\n\n[OpenClaw](https://github.com/openclaw/openclaw) 是一个强大的 AI 智能体平台（[中文汉化版](https://github.com/1186258278/OpenClawChineseTranslation)），但它的 Gateway 默认只监听本机（`127.0.0.1:18789`），手机无法直接连接。\n\nClawApp 解决了这个问题：\n\n```\n手机浏览器（任意网络）\n    ↓ WebSocket (WS / WSS)\n代理服务端（ClawApp Server，端口 3210，离线缓存）\n    ↓ WebSocket + Ed25519 设备签名\nOpenClaw Gateway（端口 18789）\n```\n\n代理服务端自动完成 Ed25519 设备签名握手认证（兼容 OpenClaw 2.13+），同时提供 H5 聊天页面，打开就能用，不需要装 App。\n\n---\n\n\u003ch2 id=\"features\"\u003e功能特性\u003c/h2\u003e\n\n- 💬 实时流式聊天（打字机效果）\n- 📷 图片收发（拍照/相册上传，AI 图片回复）\n- 📝 Markdown 渲染 + 代码高亮（XSS 防护）\n- ⚡ 快捷指令面板（/model、/think、/new 等）\n- 🔧 工具调用实时状态显示\n- 🎤 语音输入（语音转文字，需 HTTPS 环境）\n- 🤖 多智能体支持（新建会话时可选择不同 Agent）\n- 📋 会话管理（切换、新建、删除）\n- 🌙 主题切换（亮色 / 暗色 / 跟随系统）\n- 🌐 中英文切换\n- 🔄 智能重连（断线自动恢复，无闪烁，消息去重）\n- 🔒 Token / Password + Ed25519 设备认证（兼容 OpenClaw 2.13+，支持 Tailscale Funnel 密码模式）\n- 💾 离线消息缓存（IndexedDB 持久化，断网可查看历史，恢复后自动同步）\n- 👋 新用户功能引导\n- 📱 PWA 支持（添加到主屏幕，离线可用）\n- 📦 Android APK 打包（Capacitor + GitHub Actions 自动构建）\n\n---\n\n\u003ch2 id=\"screenshots\"\u003e截图预览\u003c/h2\u003e\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/image/login-page.png\" width=\"220\" alt=\"登录页\" /\u003e\u003cbr/\u003e\u003csub\u003e登录连接\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/image/chat-response.png\" width=\"220\" alt=\"AI 聊天回复\" /\u003e\u003cbr/\u003e\u003csub\u003e流式聊天\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/image/chat-commands.jpg\" width=\"220\" alt=\"快捷指令面板\" /\u003e\u003cbr/\u003e\u003csub\u003e快捷指令\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/image/session-manager.jpg\" width=\"220\" alt=\"会话管理\" /\u003e\u003cbr/\u003e\u003csub\u003e会话管理\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/image/commands-panel.png\" width=\"220\" alt=\"指令面板\" /\u003e\u003cbr/\u003e\u003csub\u003e指令面板\u003c/sub\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\u003cimg src=\"docs/image/settings-panel.jpg\" width=\"220\" alt=\"设置面板\" /\u003e\u003cbr/\u003e\u003csub\u003e设置与帮助\u003c/sub\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n\u003ch2 id=\"quickstart\"\u003e快速开始\u003c/h2\u003e\n\n### 一键部署（Mac / Linux）\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/qingchencloud/clawapp/main/install.sh | bash\n```\n\n### 一键部署（Windows PowerShell）\n\n```powershell\nirm https://raw.githubusercontent.com/qingchencloud/clawapp/main/install.ps1 | iex\n```\n\n脚本会自动检测环境、克隆仓库、安装依赖、构建前端、交互式配置 Token，并支持 PM2 常驻运行。如果本地已安装 OpenClaw，会自动读取 Gateway Token。\n\n### 前提条件\n\n- 电脑上已运行 [OpenClaw](https://github.com/openclaw/openclaw) Gateway（默认端口 18789）\n  - 推荐使用 [中文汉化版](https://github.com/1186258278/OpenClawChineseTranslation)\n- 安装了 [Node.js](https://nodejs.org/) 18+ 或 [Docker](https://www.docker.com/)\n\n### 方式一：Docker 部署（推荐）\n\n```bash\ngit clone https://github.com/qingchencloud/clawapp.git\ncd clawapp\n```\n\n在项目根目录创建 `.env` 文件：\n\n```bash\n# 手机连接时的密码（自己设一个）\nPROXY_TOKEN=my-secret-token-123\n\n# OpenClaw Gateway 的 Token（在 ~/.openclaw/gateway.yaml 里找）\nOPENCLAW_GATEWAY_TOKEN=你的gateway-token\n\n# 或者使用密码认证（Tailscale Funnel 场景必须用 password 模式）\n# 设置后自动切换为 password 认证，优先级高于 token\n# OPENCLAW_GATEWAY_PASSWORD=你的gateway-password\n```\n\n启动：\n\n```bash\ndocker compose up -d --build\n```\n\n### 方式二：直接运行\n\n```bash\ngit clone https://github.com/qingchencloud/clawapp.git\ncd clawapp\nnpm run install:all\nnpm run build:h5\ncp server/.env.example server/.env\n# 编辑 server/.env，填入你的 token\nnpm start\n```\n\n### 手机访问\n\n1. 确保手机和电脑在同一 WiFi\n2. 查看电脑 IP：\n   - Mac: `ifconfig | grep \"inet \" | grep -v 127.0.0.1`\n   - Windows: `ipconfig`\n   - Linux: `ip addr`\n3. 手机浏览器打开 `http://你的电脑IP:3210`\n4. 填入服务器地址和 Token，点击连接\n\n---\n\n\u003ch2 id=\"deploy\"\u003e部署方式\u003c/h2\u003e\n\n### 本地部署（同一网络）\n\n适合家庭/办公室使用，手机和电脑在同一 WiFi 下。\n\n```bash\ngit clone https://github.com/qingchencloud/clawapp.git\ncd clawapp \u0026\u0026 npm run install:all\nnpm run build:h5\ncp server/.env.example server/.env\n# 编辑 server/.env 填入 token\nnpm start\n```\n\n### Docker 容器部署\n\n```bash\n# 创建 .env\ncat \u003e .env \u003c\u003c 'EOF'\nPROXY_TOKEN=my-token-123\nOPENCLAW_GATEWAY_TOKEN=你的gateway-token\nALLOWED_ORIGINS=\nEOF\n\n# 构建并启动\ndocker compose up -d --build\n\n# 查看日志\ndocker compose logs -f\n```\n\nDocker 环境下会自动使用 `host.docker.internal` 连接宿主机的 Gateway。\n\n### 使用 PM2 常驻运行\n\n```bash\n# 安装 pm2\nnpm install -g pm2\n\n# 启动\npm2 start server/index.js --name clawapp\n\n# 开机自启\npm2 save \u0026\u0026 pm2 startup\n```\n\n---\n\n\u003ch2 id=\"remote\"\u003e外网访问\u003c/h2\u003e\n\n不在同一网络时，有以下方案：\n\n### 方案一：cftunnel（推荐，一条命令搞定）\n\n[cftunnel](https://github.com/qingchencloud/cftunnel) 是 Cloudflare Tunnel 一键管理 CLI，免费、自动 HTTPS、无需公网 IP。\n\n\u003e 💡 **为什么推荐 cftunnel？** 浏览器的语音输入（🎤）功能要求 HTTPS 安全上下文，局域网 HTTP 访问无法使用麦克风。cftunnel 自动提供 HTTPS，一条命令即可解锁语音输入等高级功能。\n\n**临时分享（零配置）：**\n\n```bash\n# 安装 cftunnel\ncurl -fsSL https://raw.githubusercontent.com/qingchencloud/cftunnel/main/install.sh | bash\n\n# 一条命令穿透\ncftunnel quick 3210\n# ✔ 隧道已启动: https://xxx-yyy-zzz.trycloudflare.com\n```\n\n**固定域名（需要 Cloudflare 账号 + 自有域名）：**\n\n```bash\ncftunnel init                                          # 配置 CF API Token\ncftunnel create my-tunnel                              # 创建隧道\ncftunnel add clawapp 3210 --domain chat.example.com    # 添加路由（自动创建 DNS）\ncftunnel up                                            # 启动\ncftunnel install                                       # 注册开机自启\n```\n\n\u003e 详见 [cftunnel 文档](https://cftunnel.qt.cool) · 也有 [桌面客户端](https://github.com/qingchencloud/cftunnel-app) 可视化管理\n\n### 方案二：SSH 隧道（简单快速）\n\n需要一台有公网 IP 的服务器。\n\n```bash\n# 在你的电脑上执行\nssh -f -N \\\n  -o ServerAliveInterval=15 \\\n  -o ServerAliveCountMax=4 \\\n  -R 0.0.0.0:3210:127.0.0.1:3210 \\\n  user@你的服务器IP\n```\n\n\u003e ⚠️ 服务器需要：\n\u003e - `/etc/ssh/sshd_config` 中设置 `GatewayPorts yes`\n\u003e - 防火墙放行 3210 端口\n\n手机访问 `http://服务器IP:3210`\n\n\u003e ⚠️ SSH 隧道默认是 HTTP，语音输入功能不可用。如需语音输入，请配合 Nginx SSL 或改用 cftunnel。\n\n### 方案三：Nginx 反向代理\n\n```nginx\nserver {\n    listen 443 ssl;\n    server_name clawapp.你的域名.com;\n\n    ssl_certificate /path/to/cert.pem;\n    ssl_certificate_key /path/to/key.pem;\n\n    location / {\n        proxy_pass http://127.0.0.1:3210;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n        proxy_set_header Host $host;\n        proxy_read_timeout 86400;\n    }\n}\n```\n\n### 方案对比\n\n| 方案 | 优点 | 缺点 |\n|------|------|------|\n| **cftunnel（推荐）** | **一条命令，免费，自动 HTTPS，开机自启** | **依赖 Cloudflare 服务** |\n| SSH 隧道 | 简单，无需额外软件 | 需要公网服务器，隧道可能断开 |\n| Nginx 反代 | 完全可控，自定义域名 | 需要服务器 + SSL 配置 |\n| Tailscale/ZeroTier | P2P 直连，加密 | 手机也要装客户端 |\n\n---\n\n\u003ch2 id=\"connection\"\u003e连接说明\u003c/h2\u003e\n\n打开 H5 页面后会看到连接设置页，需要填写两个字段：\n\n### 服务器地址\n\n填写运行 ClawApp Server 的电脑 IP 和端口。\n\n**局域网访问**（手机和电脑同一 WiFi）：\n```bash\n# 查看电脑 IP\n# Mac\nifconfig | grep \"inet \" | grep -v 127.0.0.1\n# Windows\nipconfig\n# Linux\nip addr\n```\n然后在 App 中填入 `你的电脑IP:3210`，例如 `192.168.1.100:3210`\n\n**外网访问**：填入公网地址，例如 `你的服务器IP:3210` 或 cftunnel 生成的域名 `xxx-yyy.trycloudflare.com`\n\n**本机访问**：直接填 `localhost:3210`\n\n### Token 获取\n\nApp 登录页的 Token 是你在部署时自己设置的 `PROXY_TOKEN`，相当于访问密码。\n\n#### 1. 如果用一键脚本部署\n\n脚本会交互式引导你设置 Token，设置完后记住即可。如果忘了，查看配置文件：\n```bash\ncat server/.env | grep PROXY_TOKEN\n```\n\n#### 2. 如果手动部署 / Docker 部署\n\nToken 在 `.env`（Docker）或 `server/.env`（手动部署）文件中配置：\n\n```bash\n# 这个是 App 登录密码，自己随便设一个\nPROXY_TOKEN=my-secret-token-123\n\n# 这个是 OpenClaw Gateway 的认证 Token（见下方获取方式）\nOPENCLAW_GATEWAY_TOKEN=你的gateway-token\n```\n\n`PROXY_TOKEN` 是你自己定义的密码，设什么 App 里就填什么。\n\n#### 3. OPENCLAW_GATEWAY_TOKEN 怎么获取\n\n这个 Token 在 OpenClaw 的配置文件 `~/.openclaw/openclaw.json` 中（JSON5 格式）：\n\n```bash\n# 查看 Gateway Token\ncat ~/.openclaw/openclaw.json | grep token\n```\n\n在配置文件中找到类似这样的结构：\n```json5\n{\n  gateway: {\n    port: 18789,\n    auth: {\n      mode: \"token\",\n      token: \"你的-gateway-token\"  // ← 复制这个值\n    }\n  }\n}\n```\n\n把 `gateway.auth.token` 的值复制到 `.env` 的 `OPENCLAW_GATEWAY_TOKEN` 中即可。\n\n#### 4. 使用密码认证（Tailscale Funnel 场景）\n\n如果你的 Gateway 使用 `password` 模式（例如通过 Tailscale Funnel 暴露），需要用 `OPENCLAW_GATEWAY_PASSWORD` 代替 Token：\n\n```json5\n// ~/.openclaw/openclaw.json\n{\n  gateway: {\n    auth: {\n      mode: \"password\",\n      password: \"你的-gateway-password\"  // ← 复制这个值\n    }\n  }\n}\n```\n\n在 `server/.env` 中设置：\n```bash\n# 密码认证（设置后自动优先于 token）\nOPENCLAW_GATEWAY_PASSWORD=你的-gateway-password\n```\n\n\u003e 💡 `OPENCLAW_GATEWAY_PASSWORD` 和 `OPENCLAW_GATEWAY_TOKEN` 二选一。设置了 password 后会自动使用密码模式，优先级高于 token。\n\n\u003e 💡 `PROXY_TOKEN`（App 登录密码）和 `OPENCLAW_GATEWAY_TOKEN`/`OPENCLAW_GATEWAY_PASSWORD`（Gateway 认证）是两个不同的概念。前者自己设，后者从 OpenClaw 配置中获取。\n\n\u003e 💡 通过 HTTPS 访问时（如 Cloudflare Tunnel），WebSocket 会自动切换为 WSS 加密连接。\n\n### H5 客户端设置\n\n点击聊天页右上角 ⚙️ 图标：\n\n- **主题**：浅色 / 深色 / 跟随系统\n- **语言**：中文 / English\n- **断开连接**：返回连接页\n\n---\n\n\u003ch2 id=\"config\"\u003e配置参数\u003c/h2\u003e\n\n| 变量 | 必填 | 默认值 | 说明 |\n|------|------|--------|------|\n| `PROXY_PORT` | 否 | `3210` | 代理服务端端口 |\n| `PROXY_TOKEN` | **是** | - | H5 客户端连接密码 |\n| `OPENCLAW_GATEWAY_URL` | 否 | `ws://127.0.0.1:18789` | Gateway 地址（Docker 下自动设为 `host.docker.internal`） |\n| `OPENCLAW_GATEWAY_TOKEN` | 二选一 | - | Gateway 认证 token |\n| `OPENCLAW_GATEWAY_PASSWORD` | 二选一 | - | Gateway 密码认证（Tailscale Funnel 场景，优先级高于 token） |\n| `MEDIA_ALLOW_ALL` | 否 | `0` | 设为 `1` 允许访问任意路径的媒体文件（默认仅 `/tmp/` 和 `/var/folders/`） |\n| `ALLOWED_ORIGINS` | 否 | - | 额外 CORS 白名单，逗号分隔 |\n\n---\n\n\u003ch2 id=\"structure\"\u003e项目结构\u003c/h2\u003e\n\n```\nclawapp/\n├── server/                # WebSocket 代理服务端\n│   ├── index.js           # Express + WS 代理 + Gateway 握手\n│   ├── package.json\n│   ├── Dockerfile\n│   └── .env.example\n├── h5/                    # H5 移动端前端\n│   ├── src/\n│   │   ├── main.js        # 入口 + 连接页\n│   │   ├── ws-client.js   # WebSocket 协议层\n│   │   ├── chat-ui.js     # 聊天 UI\n│   │   ├── session-picker.js # 会话选择器（切换/新建/删除）\n│   │   ├── message-db.js  # IndexedDB 离线消息存储\n│   │   ├── offline-queue.js # 离线队列 + 增量同步\n│   │   ├── commands.js    # 快捷指令面板\n│   │   ├── markdown.js    # Markdown 渲染 + 代码高亮\n│   │   ├── media.js       # 图片处理\n│   │   ├── i18n.js        # 国际化（中文 / English）\n│   │   ├── theme.js       # 主题管理（亮/暗/自动）\n│   │   ├── settings.js    # 设置面板\n│   │   ├── style.css      # 主样式 + 主题变量\n│   │   └── components.css # 组件样式\n│   ├── index.html\n│   └── vite.config.js\n├── android/               # Capacitor Android 项目\n├── .github/workflows/     # GitHub Actions\n│   └── build-apk.yml      # 自动构建 APK\n├── docs/                  # 文档 + GitHub Pages\n│   ├── index.html         # 产品落地页\n│   ├── pwa-and-apk-guide.md  # PWA/APK 打包指南\n│   └── image/             # 截图\n├── capacitor.config.ts    # Capacitor 配置\n├── Dockerfile             # 多阶段构建\n├── docker-compose.yml     # 生产部署\n└── README.md\n```\n\n---\n\n\u003ch2 id=\"dev\"\u003e开发\u003c/h2\u003e\n\n```bash\n# 安装依赖\nnpm run install:all\n\n# H5 开发服务器（热更新，端口 5173）\nnpm run dev:h5\n\n# 代理服务端（端口 3210）\nnpm run dev:server\n```\n\n---\n\n\u003ch2 id=\"faq\"\u003e常见问题\u003c/h2\u003e\n\n**Q: 一直显示「连接中」或报 502 Bad Gateway 错误？**\n\n1. 检查 OpenClaw Gateway 是否在运行：`curl http://localhost:18789`\n2. 后台日志如果提示 `Gateway 握手失败: NOT_PAIRED` 或 `pairing required`，是因为根据 OpenClaw 的安全机制，首次连接需要作为设备进行配对审批。**请在运行 Gateway 的服务端执行以下命令批准配对：**\n   ```bash\n   # 查看待配对设备列表并获取 requestId\n   openclaw gateway call device.pair.list --json\n   # 使用 requestId 批准配对\n   openclaw gateway call device.pair.approve --params '{\"requestId\":\"\u003c你的id\u003e\"}' --json\n   ```\n3. 确认 `OPENCLAW_GATEWAY_TOKEN` 正确\n4. Docker 部署时，Gateway 地址应为 `ws://host.docker.internal:18789`\n\n**Q: 手机打不开页面？**\n\n1. 手机和电脑是否在同一 WiFi？\n2. 电脑防火墙是否放行了 3210 端口？\n3. 地址是否用了电脑 IP（不是 localhost）？\n\n**Q: WebSocket 经常断开？**\n\n服务端内置 30 秒心跳保活，客户端也有 25 秒应用层心跳。如果还是断，检查反向代理的超时配置（建议 \u003e 60s）。SSH 隧道建议加 `-o ServerAliveInterval=15`。\n\n**Q: 能多人同时使用吗？**\n\n可以。每个连接创建独立的 Gateway 会话，但共享同一个 OpenClaw 实例。\n\n**Q: 怎么添加更多语言？**\n\n编辑 `h5/src/i18n.js`，添加新的语言包（如 `'ja'`），然后在 `settings.js` 中添加对应按钮。\n\n**Q: 语音输入按钮点了没反应？**\n\n浏览器要求 HTTPS 才能使用麦克风。局域网 HTTP 访问时，语音按钮会提示需要 HTTPS。解决方案：使用 `cftunnel quick 3210` 一键开启 HTTPS 隧道，详见[外网访问](#remote)。\n\n**Q: Docker 构建时 npm install 超时失败？**\n\n国内网络拉取 npm 包可能很慢，有几种解决方案：\n\n1. 在 Dockerfile 的 `RUN npm install` 前加镜像源：\n   ```dockerfile\n   RUN npm config set registry https://registry.npmmirror.com \u0026\u0026 npm install --omit=dev\n   ```\n2. 或者跳过 Docker，直接本地运行（推荐网络不好时使用）：\n   ```bash\n   npm run install:all \u0026\u0026 npm run build:h5\n   cp server/.env.example server/.env  # 编辑填入 token\n   npm start\n   ```\n\n**Q: 启动时报 EADDRINUSE 端口被占用？**\n\n说明 3210 端口已被其他进程占用。常见原因：\n\n1. 之前用 PM2 启动过：`pm2 stop openclaw-mobile \u0026\u0026 pm2 delete openclaw-mobile`\n2. 之前用 nohup 启动过：`lsof -i:3210 -t | xargs kill -9`\n3. Docker 容器还在跑：`docker compose down`\n\n确认端口释放后再启动：`lsof -i:3210 || echo \"端口可用\"`\n\n**Q: 用 PM2 管理时不断重启？**\n\nPM2 会在进程崩溃时自动重启。如果 Gateway 没运行或 Token 错误，服务会启动后立即因连接失败而退出，导致循环重启。解决：\n\n1. 先确认 Gateway 在运行：`curl http://localhost:18789`\n2. 检查 `server/.env` 中的 Token 是否正确\n3. 查看 PM2 日志定位问题：`pm2 logs openclaw-mobile --lines 30`\n\n**Q: 不需要修改 OpenClaw 就能用吗？**\n\n是的。ClawApp 完全兼容原生 OpenClaw，不需要安装插件、不需要改配置、不需要开额外端口。只要 Gateway 在运行（默认 `127.0.0.1:18789`），把 Token 填到 `.env` 里就能用。\n\n**Q: 部署到远程服务器后访问不了？**\n\n1. 确认防火墙放行了 3210 端口：\n   ```bash\n   # Ubuntu/Debian\n   sudo ufw allow 3210/tcp\n   # CentOS/RHEL\n   sudo firewall-cmd --add-port=3210/tcp --permanent \u0026\u0026 sudo firewall-cmd --reload\n   ```\n2. 云服务器还需要在控制台安全组中放行 3210 端口\n3. 确认服务在监听：`ss -tlnp | grep 3210`\n4. 注意：远程服务器上也需要运行 OpenClaw Gateway，否则页面能打开但无法聊天\n\n**Q: 一键脚本安装的 Node.js (nvm) 在 PM2 重启后找不到？**\n\nnvm 安装的 Node.js 需要 source 才能生效。如果 PM2 通过 `pm2 startup` 设置了开机自启，重启后可能找不到 node。解决：\n\n```bash\n# 获取 node 的绝对路径\nwhich node  # 例如 /root/.nvm/versions/node/v22.22.0/bin/node\n\n# 用绝对路径启动 PM2\npm2 startup\npm2 save\n```\n\n或者将 nvm 的 node 软链到系统路径：\n```bash\nsudo ln -sf $(which node) /usr/local/bin/node\nsudo ln -sf $(which npm) /usr/local/bin/npm\nsudo ln -sf $(which pm2) /usr/local/bin/pm2\n```\n\n**Q: 能部署到没有 OpenClaw 的服务器上吗？**\n\n可以部署，但需要通过 SSH 隧道或反向代理将远程服务器的请求转发回运行 OpenClaw 的电脑。典型场景：\n\n```\n手机 → 远程服务器 ClawApp(:3210) → SSH隧道 → 本地电脑 Gateway(:18789)\n```\n\n在远程服务器上：\n```bash\n# 将远程的 18789 端口转发到本地电脑的 Gateway\nssh -f -N -L 127.0.0.1:18789:127.0.0.1:18789 user@你的电脑IP\n```\n\n这样远程 ClawApp 就能通过 `ws://127.0.0.1:18789` 连接到你本地的 Gateway。\n\n---\n\n\u003ch2 id=\"security\"\u003e安全建议\u003c/h2\u003e\n\n- 务必设置强 `PROXY_TOKEN`（建议 32 位以上随机字符串）\n  ```bash\n  openssl rand -hex 24\n  ```\n- Gateway Token 只在服务端 `.env` 中，不会暴露给客户端\n- 公网访问建议使用 HTTPS（Cloudflare Tunnel 或 Nginx + SSL）\n- 可选：使用 [Cloudflare Access](https://www.cloudflare.com/products/zero-trust/) 添加额外认证\n- 部署到公网服务器时，务必设置防火墙规则，只开放必要端口（3210）\n- 不要将 `.env` 文件提交到 Git（已在 `.gitignore` 中排除）\n\n---\n\n\u003ch2 id=\"related\"\u003e相关项目\u003c/h2\u003e\n\n- [OpenClaw](https://github.com/openclaw/openclaw) - AI 智能体平台\n- [OpenClaw 中文汉化版](https://github.com/1186258278/OpenClawChineseTranslation) - 社区汉化\n- [cftunnel](https://github.com/qingchencloud/cftunnel) - Cloudflare Tunnel 一键管理 CLI（推荐用于外网访问）\n- [cftunnel-app](https://github.com/qingchencloud/cftunnel-app) - cftunnel 桌面客户端\n\n---\n\n\u003ch2 id=\"community\"\u003e社区交流\u003c/h2\u003e\n\n欢迎加入社区，交流使用心得、反馈问题、获取最新动态：\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/U9AttmsNHh\"\u003e\u003cimg src=\"https://img.shields.io/badge/Discord-加入社区-5865F2?style=for-the-badge\u0026logo=discord\u0026logoColor=white\" alt=\"Discord\"\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://yb.tencent.com/gp/i/LsvIw7mdR7Lb\"\u003e\u003cimg src=\"https://img.shields.io/badge/元宝派-加入圈子-FF6A00?style=for-the-badge\u0026logo=tencent-qq\u0026logoColor=white\" alt=\"元宝派\"\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://qt.cool/c/OpenClaw\"\u003e\u003cimg src=\"https://img.shields.io/badge/QQ群-加入交流-12B7F5?style=for-the-badge\u0026logo=tencent-qq\u0026logoColor=white\" alt=\"QQ群\"\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"https://qt.cool/c/OpenClawWx\"\u003e\u003cimg src=\"https://img.shields.io/badge/微信群-加入交流-07C160?style=for-the-badge\u0026logo=wechat\u0026logoColor=white\" alt=\"微信群\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n### QQ 交流群\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"docs/image/OpenClaw-QQ.png\" alt=\"QQ交流群\" width=\"200px\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e扫码或 \u003ca href=\"https://qt.cool/c/OpenClaw\"\u003e点击链接\u003c/a\u003e 加入 | 2000 人大群，满员自动切换\u003c/em\u003e\n\u003c/p\u003e\n\n### 微信交流群\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://qt.cool/c/OpenClawWx\"\u003e\n    \u003cimg src=\"docs/image/OpenClawWx.png\" alt=\"微信交流群\" width=\"200px\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e扫码或 \u003ca href=\"https://qt.cool/c/OpenClawWx\"\u003e点击链接\u003c/a\u003e 加入 | 碰到问题也可以直接在群内反馈\u003c/em\u003e\n\u003c/p\u003e\n\n- 🎮 [Discord 社区](https://discord.gg/U9AttmsNHh) — 国际交流频道\n- 🤖 [元宝派社群圈子](https://yb.tencent.com/gp/i/LsvIw7mdR7Lb) — 腾讯元宝派讨论区\n\n---\n\n\u003cdetails id=\"english\"\u003e\n\u003csummary\u003e\u003cstrong\u003eEnglish Documentation\u003c/strong\u003e\u003c/summary\u003e\n\n### What is this?\n\nClawApp is an H5 mobile chat client that lets you chat with your [OpenClaw](https://github.com/openclaw/openclaw) AI agent from any phone browser.\n\n### Quick Start\n\n**Docker:**\n```bash\ngit clone https://github.com/qingchencloud/clawapp.git\ncd clawapp\necho 'PROXY_TOKEN=your-token' \u003e .env\necho 'OPENCLAW_GATEWAY_TOKEN=your-gw-token' \u003e\u003e .env\n# Or use password auth: echo 'OPENCLAW_GATEWAY_PASSWORD=your-gw-password' \u003e\u003e .env\ndocker compose up -d --build\n```\n\n**Direct:**\n```bash\ngit clone https://github.com/qingchencloud/clawapp.git\ncd clawapp \u0026\u0026 npm run install:all \u0026\u0026 npm run build:h5\ncp server/.env.example server/.env  # edit tokens\nnpm start\n```\n\nOpen `http://your-ip:3210` on your phone.\n\n### Remote Access\n\n- **cftunnel (recommended)**: `cftunnel quick 3210` — [github.com/qingchencloud/cftunnel](https://github.com/qingchencloud/cftunnel)\n- **SSH Tunnel**: `ssh -f -N -R 0.0.0.0:3210:localhost:3210 user@server`\n- **Nginx**: Configure WebSocket proxy to port 3210\n\n### Features\n\nReal-time streaming chat, image send \u0026 receive, Markdown rendering, offline message cache (IndexedDB), Ed25519 device auth, session management, dark/light/auto theme, English/Chinese i18n, smart reconnect (no flicker), XSS protection, token auth.\n\n\u003c/details\u003e\n\n---\n\n## 贡献者\n\n感谢所有为 ClawApp 做出贡献的开发者！\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/1186258278\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/42165041?v=4\" width=\"64\" height=\"64\" style=\"border-radius:50%\" alt=\"1186258278\" /\u003e\u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://github.com/youyli03\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/123646696?v=4\" width=\"64\" height=\"64\" style=\"border-radius:50%\" alt=\"youyli03\" /\u003e\u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://github.com/2221186349\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/78676214?v=4\" width=\"64\" height=\"64\" style=\"border-radius:50%\" alt=\"2221186349\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  由 \u003ca href=\"https://qt.cool\"\u003e晴辰云\u003c/a\u003e 开发维护\u003cbr/\u003e\n  \u003ca href=\"https://clawapp.qt.cool\"\u003eclawapp.qt.cool\u003c/a\u003e\n\u003c/p\u003e\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqingchencloud%2Fclawapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqingchencloud%2Fclawapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqingchencloud%2Fclawapp/lists"}