ClawChat2

English

ClawChat2 is an unofficial Android fork derived from the official OpenClaw Android client in openclaw/openclaw -> apps/android.

This fork focuses on one product goal: a simple, direct, chat-first way to talk with OpenClaw agents from Android, with stronger media receive/render support and practical attachment upload for image, audio, video, and regular file messages.

The short rationale for the fork is documented in WHY_THIS_FORK.md.

Project Status

• Baseline version: 0.2.8
• Android compatibility baseline: minSdk 30 (Android 11+)
• Stage: early, experimental, not release-hardened
• Scope: independent community fork, not an official OpenClaw distribution

Fork Positioning

Compared with the upstream Android client, this fork currently emphasizes:

• chat as the primary surface
• direct agent conversations
• openclaw-webchat as the source of truth for contacts and chat history
• simplified chat-first navigation
• selectable app theme mode with dark-mode support
• WeChat-style continuous contacts list with larger avatars and a single subtle divider between adjacent rows
• continuous chat-message presentation with speaker/time metadata outside the bubble at the top-left and synced user display name
• optional chat reply readout with a lightweight speaker toggle in the composer action row
• quick composer controls for send/stop, /new, model switch, and thinking switch directly under the input box
• denser chat transcript layout with left-aligned bubbles, smaller symmetric side padding, screenshot-aligned light/dark surfaces, and clearer color separation between user, agent, and system messages
• single-line plain-text bubbles now shrink to content width, while multi-line text and attachment-bearing messages keep the wider conversation width
• solid green user bubbles now use dark text in both light and dark mode for stronger readability against the brighter reply fill
• edge-to-edge large chat images with fullscreen tap-to-open / tap-to-close viewing, while smaller images keep their natural size instead of being upscaled
• borderless icon-only composer quick controls that keep attachment, new-chat, model, thinking, readout, and send/stop visible in one row
• enhanced agent-to-client media handling
• generic user attachment upload for images, audio, video, and regular files
• inline chat videos now show a first-frame preview before fullscreen playback opens
• practical Android playback stability improvements for fullscreen image/video viewing
• streamed fullscreen video playback for large remote files
• practical gateway access patterns including Tailscale-friendly usage

This repository explores a narrower Android UX for users who mainly want to open the app and chat with their OpenClaw agents directly, without extra shell complexity, unnecessary setup, or registration overhead beyond what is required to connect to their own OpenClaw gateway.

Important Notice

• This repository is based on code from the official OpenClaw project.
• It is not published by, affiliated with, or endorsed by the OpenClaw maintainers.
• Upstream references are included only to document code origin and compatibility targets.
• Original upstream license and attribution are preserved in LICENSE, FORK_NOTES.md, and THIRD_PARTY_LICENSES.

Related docs:

• CONTRIBUTING.md
• OPENCLAW_AGENT_SETUP.md
• PUBLIC_RELEASE_CHECKLIST.md
• RELEASING.md
• RELEASE_NOTES_v0.2.8.md
• WHY_THIS_FORK.md

Demo And Preview

Intro video:

Watch on Bilibili

Current app preview:

OpenClaw-Side Setup

Before a user continues with ClawChat2 setup, they should first ask their agent or operator to install claw-webchat on the server side by following AGENT_INSTALL_NETWORK.md.

If you want an OpenClaw-side agent or operator to prepare a gateway specifically for ClawChat2, start with that claw-webchat guide first, then use OPENCLAW_AGENT_SETUP.md as the app-specific companion guide.

Important:

• setup code is the preferred path
• for manual or Tailscale setup, the user should also fill in the gateway token
• without that token, the device may not appear in openclaw devices list when approval is required
• if OpenClaw uses gateway.tailscale.mode=serve, setup-code/QR routes are typically wss://<magicdns> on port 443
• if gateway.tailscale.mode=serve is configured but tailscale serve status shows no published route, the advertised .ts.net URL is not actually reachable yet
• on Android, the Tailscale app must be actually connected; "installed and logged in" is not enough
• if pairing requests keep rotating while the phone retries, approve with openclaw devices approve --latest instead of copying an older requestId
• the current fork now keeps default Android operator pairing on operator.read + operator.write, so standard local approval no longer depends on operator.talk.secrets

Media Support

ClawChat2 currently supports structured agent-sent media attachments and user-originated generic attachment upload:

• image receive and fullscreen viewing
• audio receive and playback
• video receive, preview, and fullscreen playback
• inline chat video cards now try to show the first video frame instead of a generic black placeholder
• streamed remote video playback without requiring a full pre-download
• chat-side upload of images, audio, video, and regular files to openclaw-webchat

Current local media contract in this fork prefers gateway-relative fields:

[
  { "type": "text", "text": "Optional caption" },
  {
    "type": "image|audio|video|file",
    "mimeType": "real MIME type",
    "fileName": "original file name",
    "mediaPath": "/media/<token>",
    "mediaPort": 39393,
    "mediaUrl": "http://10.0.2.2:39393/media/<token>",
    "mediaSha256": "<sha256>",
    "sizeBytes": 123456
  }
]

Notes:

• mediaPath + mediaPort are the preferred fields in this fork
• mediaUrl is retained as a compatibility fallback
• the current user-originated picker flow now supports image, audio, video, and generic file uploads through the same openclaw-webchat upload path
• generic files now appear in the transcript as file cards instead of being treated as unsupported attachments
• inline chat video cards now reuse the playable video source to show a first-frame preview before fullscreen playback
• fullscreen video playback now prefers streamed playback via Android Media3/ExoPlayer, with local-file fallback only when needed

Operational guides:

• AGENT_MEDIA_SEND.md
• AGENT_MEDIA_SERVER.md

Build

./gradlew :app:assemblePlayDebug
./gradlew :app:compilePlayDebugKotlin
./gradlew :app:testPlayDebugUnitTest

Install and launch:

./gradlew :app:installPlayDebug
adb shell am start -n ai.openclaw.app/.MainActivity

Current local verification:

• the current main workspace was compiled, installed, and launched successfully on the local Android 15 emulator clawchat2_api35 on 2026-03-24
• the current codex/upstream-bridge-pass workspace was rebuilt as playDebug and verified again on 2026-03-26 after Tailscale Serve recovery, manual TLS fallback, and Android pairing-scope reduction
• a real Huawei Mate60 (BRA-AL00, Android 12 / SDK 31) completed Tailscale setup-code pairing successfully on 2026-03-26 after the route and pairing fixes
• a real Huawei Mate60 (BRA-AL00, Android 12 / SDK 31) also verified chat reply readout successfully on 2026-03-28 after adding Android 11+ TTS package visibility and moving the readout toggle into the composer action row
• a real Huawei Mate60 (BRA-AL00, Android 12 / SDK 31) also verified generic attachment upload successfully on 2026-03-28 by sending a Markdown file through the chat attachment button
• a real Redmi K20 (c2f22adf) also verified the new composer-side /new shortcut successfully on 2026-03-29 after adding the N action next to send
• a real Redmi K20 (c2f22adf) also verified the 2026-03-29 public-release chat visual polish build after the denser bubble pass, screenshot-aligned light/dark chat palette, dark-text user reply bubbles, and fullscreen image tap-to-dismiss refinements
• the promoted main release baseline was rebuilt again on 2026-03-30 after merging codex/ui-palette-pass, and this release line now includes the screenshot-aligned palette plus onboarding guidance that explicitly tells users to give the claw-webchat install guide to their agent first
• the current release line now also suppresses automatic pairing-request churn while approval is pending, so openclaw devices approve --latest no longer races against repeated Android reconnect attempts during setup-code onboarding
• the onboarding welcome page now starts with an explicit app-language choice, so users can pick Chinese, English, or follow-system before the rest of the setup flow continues

Releases

• Public end users should install APKs from GitHub Releases instead of building from source.
• Early public builds should be marked as Pre-release.
• Public APKs should be signed with the fork maintainer's own release key.
• Release notes should clearly state that this is an unofficial OpenClaw fork.

Current release guidance is documented in RELEASING.md and RELEASE_NOTES_v0.2.8.md.

Development Notes

• Treat this repository as an early-stage fork, not a drop-in upstream replacement.
• Keep fork-specific behavior clearly separated from changes that could plausibly go upstream later.
• Do not add personal endpoints, private tokens, machine-specific paths, or test-only defaults to committed code.
• Use status.md as the public project status summary for this fork.

中文

ClawChat2 是一个基于官方 OpenClaw Android 客户端 openclaw/openclaw -> apps/android 派生出来的非官方 Android 分叉项目。

这个分叉主要围绕一个产品目标展开：在 Android 上以更简单、更直接、聊天优先的方式与 OpenClaw 的 agent 对话，同时增强图片、音频、视频等消息的接收与渲染能力，并补上用户侧对常规文件附件的上传能力。

关于为什么要做这个分叉的简要说明见 WHY_THIS_FORK.md。

项目状态

• 当前基线版本：0.2.8
• Android 兼容基线：minSdk 30（Android 11+）
• 当前阶段：早期、实验性、尚未达到发布级稳定
• 项目定位：独立社区分叉，不是官方 OpenClaw 发布版本

分叉定位

相较于上游 Android 客户端，这个分叉当前更强调：

• 聊天是主界面与主入口
• 与 agent 的直接对话
• 更简化、聊天优先的导航方式
• 支持可切换的应用主题模式与深色模式
• 更强的 agent 到客户端媒体处理能力
• 联系人页采用连续列表布局，相邻联系人之间只保留一条浅分隔线
• 输入框下方现在也提供轻量快捷控制，包括 send/stop、/new、模型切换和 thinking 切换
• 对话记录区域进一步收敛为左对齐、左右留白更小且对称的高密度气泡布局，并将发言人和时间移到气泡外左上角，通过颜色区分用户、agent 与 system 消息
• 单行纯文本消息会按内容宽度收缩；多行文本消息和带附件消息继续保持更宽的对话宽度
• 用户回复气泡现在在浅色和深色模式下都统一使用实心绿色底配深色文字，提升亮色气泡上的可读性
• 大图会尽量铺满气泡内容区，小图则保持原始显示尺寸不过度放大，同时支持单击进入全屏、全屏内再单击返回
• 输入框下方的快捷操作现已收敛为无外框的纯图标按钮，一行内同时显示附件、新会话、模型、thinking、朗读与发送/停止
• 支持用户侧上传图片、音频、视频和普通文件给 agent
• 聊天中的视频卡片现在会尽量显示视频首帧预览，而不是统一黑色占位块
• 更稳定的 Android 图片/视频全屏播放体验
• 更贴近实际使用的网关接入方式，包括对 Tailscale 场景的友好支持

这个仓库的目的，是为那些主要诉求就是“打开 app 直接和自己的 OpenClaw agent 聊天”的用户，探索一种更窄、更直接的 Android 交互方式，尽量减少额外壳层、繁琐设置和不必要的注册/引导负担。

重要说明

• 本仓库基于官方 OpenClaw 项目的代码演化而来。
• 本仓库不是官方 OpenClaw 仓库，也不代表 OpenClaw 官方立场。
• 文档中提及上游项目，仅用于说明代码来源与兼容目标。
• 上游许可证与归属说明保留在 LICENSE、FORK_NOTES.md 和 THIRD_PARTY_LICENSES 中。

相关文档：

• CONTRIBUTING.md
• OPENCLAW_AGENT_SETUP.md
• PUBLIC_RELEASE_CHECKLIST.md
• RELEASING.md
• RELEASE_NOTES_v0.2.8.md
• WHY_THIS_FORK.md

视频与预览

介绍视频：

Bilibili 观看链接

当前应用预览：

OpenClaw 侧准备

在用户继续 ClawChat2 安装前，应先让 agent 或 operator 按照这个服务端文档安装 claw-webchat： AGENT_INSTALL_NETWORK.md

如果你希望让 OpenClaw 侧的 agent 或操作者为 ClawChat2 准备 gateway，请先完成上面的 claw-webchat 服务端安装，再参考 OPENCLAW_AGENT_SETUP.md 完成面向 ClawChat2 的补充说明。

重要说明：

• 首选方式仍然是 setup code
• 如果用户选择手动设置或 Tailscale 设置，也应填写 gateway token
• 没有这个 token 时，设备在需要批准时可能不会出现在 openclaw devices list 中

媒体支持

ClawChat2 当前支持 agent 发送的结构化媒体消息，也支持用户从聊天页上传通用附件：

• 图片接收与全屏查看
• 音频接收与播放
• 视频接收、预览与全屏播放
• 聊天页上传图片、音频、视频和普通文件到 openclaw-webchat

当前分叉中，本地媒体协议优先使用网关相对字段：

[
  { "type": "text", "text": "Optional caption" },
  {
    "type": "image|audio|video|file",
    "mimeType": "real MIME type",
    "fileName": "original file name",
    "mediaPath": "/media/<token>",
    "mediaPort": 39393,
    "mediaUrl": "http://10.0.2.2:39393/media/<token>",
    "mediaSha256": "<sha256>",
    "sizeBytes": 123456
  }
]

说明：

• mediaPath + mediaPort 是本分叉当前优先使用的字段
• mediaUrl 保留作为兼容性 fallback
• 当前用户侧附件选择器已经支持 image、audio、video 和通用 file
• 普通文件现在会在聊天记录中显示为文件卡片，而不是被当成不支持的附件
• 聊天中的视频卡片现在会复用可播放视频源提取首帧预览，再进入全屏播放
• 视频全屏当前优先走 Android Media3/ExoPlayer 的流式播放，必要时再回退到本地文件路径

构建

./gradlew :app:assemblePlayDebug
./gradlew :app:compilePlayDebugKotlin
./gradlew :app:testPlayDebugUnitTest

安装并启动：

./gradlew :app:installPlayDebug
adb shell am start -n ai.openclaw.app/.MainActivity

当前本地验证结论：

• 当前 main 工作区已于 2026-03-24 在本地 Android 15 模拟器 clawchat2_api35 上成功编译、安装并启动
• 当前 main 工作区也已于 2026-03-28 在 Huawei Mate60（BRA-AL00，Android 12 / SDK 31）上完成通用附件上传验证，测试文件为 Markdown，验证结果通过
• 当前 main 工作区也已于 2026-03-29 在 Redmi K20（设备 c2f22adf）上完成聊天页 N 按钮验证，确认该按钮会执行 /new
• 当前 codex/ui-palette-pass 工作区也已于 2026-03-29 在 Redmi K20（设备 c2f22adf）上完成聊天配色参考图对齐与用户气泡深色文字版本的编译、安装与前台启动验证
• 已提升为新主线的 main 工作区又已于 2026-03-30 完成 codex/ui-palette-pass 合并后的公开发布准备，并补上 onboarding 首页提示，明确要求用户先把 claw-webchat 安装文档发给 agent

操作文档：

• AGENT_MEDIA_SEND.md
• AGENT_MEDIA_SERVER.md

构建

./gradlew :app:assembleDebug
./gradlew :app:compileDebugKotlin
./gradlew :app:testDebugUnitTest

安装并启动：

./gradlew :app:installDebug
adb shell am start -n ai.openclaw.app/.MainActivity

发行版本

• 面向公开用户时，应优先通过 GitHub Releases 分发 APK，而不是要求用户自行编译源码。
• 首批公开版本建议标记为 Pre-release。
• 对外发布的 APK 应使用分叉维护者自己的 release key 签名。
• Release 说明中应明确写明这是非官方 OpenClaw 分叉。

当前发行流程与首版说明见 RELEASING.md 和 RELEASE_NOTES_v0.2.8.md。

开发说明

• 请把这个仓库视为早期分叉项目，而不是上游的直接替代品。
• 分叉专属行为要和未来可能 upstream 的改动保持清晰边界。
• 不要提交个人 endpoint、私有 token、机器本地路径或测试专用默认值。
• status.md 是这个分叉的公开项目状态摘要。