lark-remote-claude

v1.0.6

Published

5 days ago

Remote Claude Lark bridge: run Claude Code/Codex from Feishu (Lark) with shared terminal sessions and interactive cards.

Lark Remote Claude

English | 简体中文

在电脑终端运行 Claude Code / Codex，同时通过飞书（Feishu / Lark）实时查看输出、发送指令、点击交互按钮（选项/权限确认）。

Feishu/Lark remote terminal bridge for Claude Code and Codex.

Keywords: remote claude lark, lark remote claude, feishu claude code.

这个项目解决什么问题

离开工位也能继续盯 AI：在健身房、通勤、接娃路上，只要电脑联网，就能在手机飞书里继续操作同一个 Claude / Codex 会话。
多个终端 + 飞书共享同一个会话；终端输出按流式卡片同步到飞书，支持交互按钮（权限确认、选项点击）。
一个群 = 一个会话工作面板：群名带 session 名、菜单显示 cwd/CLI/启动时间，多个群也能一眼对上本地哪个终端。
进程异常退出不丢失："AI 阅读飞书群历史"重建上下文，恢复后续聊不掉链子。
连接断了会自我修复：watchdog 监控 WS 状态，长时间断开主动推提醒、必要时自动重启。

版本更新记录

完整版本历史请见 CHANGELOG.md。

环境要求

macOS 或 Linux
uv
tmux
Claude Code CLI 或 Codex CLI

安装

方式 1：npm（推荐）

npm install -g lark-remote-claude

方式 2：源码安装

git clone https://github.com/ShellyDeng08/lark-remote-claude.git
cd lark-remote-claude
./init.sh

安装后请重启终端，使快捷命令生效。

用户入口（先看这个）

普通用户完整手册： https://github.com/ShellyDeng08/lark-remote-claude/blob/main/docs/USER_GUIDE.md
飞书客户端运维与排障： https://github.com/ShellyDeng08/lark-remote-claude/blob/main/docs/LARK_CLIENT_GUIDE.md

3 分钟快速开始（推荐）

# 1) 安装（全局）
npm install -g lark-remote-claude

# 2) 在你的项目目录启动（会自动启动飞书客户端）
cl

# 3) 若飞书侧无响应，执行一次重连
remote-claude lark restart

# 4) 在飞书里给机器人发 /menu，选择会话后直接开始聊天

说明：remote-claude lark restart 不需要每次都执行；首次安装后、修改飞书凭证后，或连接异常时执行一次即可。

你也可以使用以下快捷命令：

cla   # 启动 Claude（默认会话名为当前目录）
cl    # 启动 Claude（跳过权限确认）
cx    # 启动 Codex（跳过权限确认）
cdx   # 启动 Codex（需要确认权限）

常用管理命令：

remote-claude list
remote-claude attach <会话名>
remote-claude kill <会话名>
remote-claude status <会话名>

启用飞书（需要一次管理员配置）

如果你只在终端使用，可跳过本节。

1) 在飞书开放平台创建企业自建应用

地址：https://open.feishu.cn/
获取 App ID 和 App Secret
添加应用能力：机器人

2) 配置事件与回调（长连接）

事件配置：使用长连接接收事件，并添加：
- im.message.receive_v1（接收消息 v2.0）
回调配置：使用长连接接收回调，并添加：
- card.action.trigger（卡片回传交互）

3) 配置权限（最小必需）

在「权限管理 -> 批量导入/导出权限」导入以下 tenant scopes：

{
  "scopes": {
    "tenant": [
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.id:readonly",
      "im:chat.members:read",
      "im:chat.members:write_only",
      "im:chat:create",
      "im:chat:read",
      "im:chat:update",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message.urgent",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:message:update",
      "im:resource"
    ]
  }
}

4) 发布应用

在飞书开放平台创建版本并发布到线上。

5) 在本机写入飞书凭证

首次运行 cla / cl 会提示填写；或手动编辑 ~/.remote-claude/.env：

FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx

飞书端怎么用

启动/检查飞书客户端

remote-claude lark start
remote-claude lark status
remote-claude lark restart
remote-claude lark stop

在飞书中操作

搜索并打开你的机器人
发送 /menu
在菜单卡片里连接会话
直接发消息给 Claude/Codex

常用命令：

/menu 打开仪表盘（快速入口 + 偏好开关，移动端友好）
/list 完整会话列表（活跃会话 / 已绑定群 / 孤儿群 / 翻页）
/attach <会话名> 连接会话
/detach 断开当前连接
/status 当前连接状态、绑定群、CLI 等信息
/groups 查看本地已知群（私聊专用）；/groups check 触发一次飞书 API 强校验
/help 查看帮助

可选功能

自定义环境变量（`~/.remote-claude/.env`）

除了 FEISHU_APP_ID / FEISHU_APP_SECRET，还支持以下常用自定义配置：

# 用户白名单
ENABLE_USER_WHITELIST=true
ALLOWED_USERS=ou_xxx,ou_yyy

# 群聊名显示前缀
GROUP_NAME_PREFIX=【Remote-Claude】

# 自定义 Claude CLI 命令
CLAUDE_COMMAND=claude

# 流式卡片单卡 block 上限
MAX_CARD_BLOCKS=50

# 日志级别
LARK_LOG_LEVEL=INFO
SERVER_LOG_LEVEL=INFO

# SOCKS 代理环境下绕过飞书请求代理
LARK_NO_PROXY=1

# WebSocket 健康监控（默认开启，阈值可调）
# 断开多久后给用户推提醒卡片（秒）
LARK_WS_NOTIFY_SECONDS=60
# 断开多久后自动 self-restart 进程（秒）
LARK_WS_RESTART_SECONDS=300
# watchdog 巡检间隔（秒）
LARK_WS_WATCHDOG_INTERVAL=30
# 关闭自动 self-restart（仅推提醒，不重启）
# LARK_WS_AUTO_RESTART=false

# 用户 OAuth（高级能力）
ENABLE_USER_AUTH=true
OAUTH_SERVER_PORT=8080
# OAUTH_REDIRECT_URI=http://localhost:8080/oauth/callback

# 统计（可选）
# MIXPANEL_TOKEN=your_mixpanel_token

# AI 分析降级备用（可选）
# ANTHROPIC_API_KEY=sk-ant-xxx

完整变量清单见仓库根目录 .env.example。

用户 OAuth（高级能力，可选）

仅当你需要“以用户身份访问更多飞书资源”时启用。通过上面的 OAuth 相关环境变量配置（ENABLE_USER_AUTH、OAUTH_SERVER_PORT、OAUTH_REDIRECT_URI）。

Telemetry 与隐私

本工具默认不收集任何遥测数据。 安装与日常使用都不会向第三方发送数据（除你显式调用的飞书 API、AI CLI 流量等）。

仓库里的 stats/ 模块是一个可选的本地事件记录器：事件写入 ~/.remote-claude/stats.db 本地 SQLite，不上传——除非你自己显式设置 MIXPANEL_TOKEN 环境变量指向你自己的 Mixpanel 项目，事件才会被转发到那里。

如果你想绝对保证零网络遥测（即使某些集成意外设置了 MIXPANEL_TOKEN），设置任一环境变量即可：

export DO_NOT_TRACK=1
# 或
export DISABLE_TELEMETRY=1

任何配置下都不会收集：hostname、用户名、IP、会话内容、命令、文件、终端输出、飞书消息内容、飞书 user ID。

常见问题

1) 飞书里搜不到机器人

检查应用是否已发布到线上
确认你和机器人在同一飞书组织

2) 飞书发消息没反应

先看 remote-claude lark status
检查 FEISHU_APP_ID / FEISHU_APP_SECRET 是否正确
检查开放平台事件/回调是否按上文配置

3) 终端与飞书显示不一致

先查看 docs/LARK_CLIENT_GUIDE.md 的排障部分。

关键词（便于搜索）

Claude Code, Codex, Feishu bot, Lark bot, remote terminal, shared CLI session, AI coding assistant, remote-claude, lark-remote-claude.

文档

docs/USER_GUIDE.md：面向使用者的完整操作手册
docs/LARK_CLIENT_GUIDE.md：飞书客户端运维与排障
CLAUDE.md：项目架构与开发说明