企业官网建设流程全解析

如何让 lark-coding-agent-bridge 7×24 小时稳定在线：launchd、systemd 与 Windows 计划任务三平台部署指南

【免费下载链接】lark-coding-agent-bridgeBot that bridges Feishu/Lark messenger with a local Claude Code or Codex CLI. Streaming cards, per-chat sessions, multiple workspaces项目地址: https://gitcode.com/gh_mirrors/fe/lark-coding-agent-bridge

lark-coding-agent-bridge 是一个把飞书 / Lark 消息桥接到本机 Claude Code 或 Codex CLI 的编程机器人：在飞书里发消息，它就用流式卡片实时返回 AI 编程助手的回答与工具调用。想要 7×24 小时稳定在线，关键是把 bot 从"前台进程"升级为操作系统托管的后台服务——macOS 用 launchd、Linux 用 systemd、Windows 用计划任务，一条start命令全部搞定。

为什么必须用系统服务托管 🛡️

用lark-channel-bridge run前台运行时，bot 的生命周期和终端窗口绑定：Ctrl-C或合上笔记本盖子，机器人立刻下线。系统服务则提供三大保障：

• 开机/登录自启：重启电脑后自动恢复服务，不用人工介入；
• 崩溃兜底：macOS 的KeepAlive与 systemd 的Restart=always会在进程退出后自动拉起；
• 日志归集：标准输出/错误统一落到本地日志文件，方便排查。

三个平台的差异全部由项目内置的服务适配层抹平，核心逻辑分别位于 src/daemon/launchd.ts、src/daemon/systemd.ts、src/daemon/schtasks.ts，并由 src/daemon/service-adapter.ts 统一调度。

部署前置条件：先全局安装

⚠️ 这是官方明确强调的一点：服务层命令必须先全局安装，不能直接用npx启动。

后台服务的定义文件会记录 bridge CLI 的绝对路径；如果路径来自 npm 的临时缓存（npx场景），缓存被清理后 daemon 就会起不来。

npm i -g lark-channel-bridge # 或 pnpm add -g lark-channel-bridge

同时确认本机已安装并登录claude或codexCLI，且 Node.js 版本 >= 20.12.0。首次配置用扫码向导完成：

lark-channel-bridge run

首次运行会弹出二维码，用飞书扫码、选择或创建 PersonalAgent 应用，配置写入~/.lark-channel/config.json。确认 bot 能正常收发消息后，Ctrl-C停掉前台进程，进入正式的后台部署。

一键注册后台服务：最快配置方法

确认前台可用后，只需一条命令：

lark-channel-bridge start

这条命令背后做了完整的动作链（见 src/cli/commands/service.ts）：

1. 检查当前 profile 与运行锁，防止重复实例抢占；
2. 按当前系统写出服务定义（plist / unit / 计划任务），并记录当时的 Node 路径、PATH 环境变量——这样 daemon 在极简环境里也能找到claude、codex；
3. 若旧实例还在运行，先停掉并等待其彻底退出，再启动新实例；
4. 轮询进程注册表，直到 bot 与飞书完成 WebSocket 握手，打印"✓ 已启动 bot: xxx"才算真正在线。

日常操作全部支持--profile <name>指定具体 profile：

lark-channel-bridge stop --profile claude lark-channel-bridge restart --profile claude lark-channel-bridge status --profile claude lark-channel-bridge unregister --profile claude

三平台服务速查表

各平台生成的服务名与关键行为一览（命名规则见 src/daemon/paths.ts）：

三个平台的 daemon 日志都落在同一处，方便记忆：

~/.lark-channel/profiles/<profile>/logs/daemon/daemon-stdout.log ~/.lark-channel/profiles/<profile>/logs/daemon/daemon-stderr.log

macOS launchd 部署详解

macOS 上start生成的 plist 位于~/Library/LaunchAgents/，通过launchctl bootstrap加载、launchctl kickstart -k重启。有两个容易踩的坑，项目已在源码层面处理（src/daemon/launchd.ts）：

• stop 后再 start 不生效：bootout只是会话级卸载，plist 里的RunAtLoad会在下次登录时把 daemon 悄悄拉回来；被disable过的 job 即使 bootstrap 成功也不会启动。因此start每次都先enable再bootstrap。
• 报Bootstrap failed: 5: Input/output error：常见原因是旧实例还在收尾。稍等几秒重试，或彻底清理后重启：

lark-channel-bridge unregister lark-channel-bridge start

另外，stop的语义是"停止且不再自启"（bootout + disable），保证 stop 就是彻底停掉；restart则保留自启、原地重启。

Linux systemd 用户服务：两点必知

start会在~/.config/systemd/user/写入单元文件并执行enable --now（src/daemon/systemd.ts）。单元文件里有几个关键配置：

• Restart=always+RestartSec=5：崩溃后 5 秒自动拉起，且带回退间隔，避免崩溃循环打满 CPU；
• Wants=network-online.target：等网络就绪后再启动，减少首次启动时的连接失败。

两点需要注意：

1. 用户级服务默认随注销退出。如果希望机器不登录也能跑 bot（比如当轻量服务器），执行一次：

loginctl enable-linger $USER

2. 修改单元文件后无需手动 daemon-reload，start/unregister会自动执行。

Windows 计划任务部署：无需管理员

Windows 适配层（src/daemon/schtasks.ts）会生成一个.cmd启动器脚本并注册计划任务，有 3 个贴心设计：

• 登录触发（ONLOGON）：每次登录 Windows 自动拉起 bot；
• 当前用户权限（/RL LIMITED）：注册任务不需要管理员提权；
• .cmd包装器：负责写入 PATH、LARK_CHANNEL_HOME环境变量，并把输出追加到日志文件，重启后日志历史不丢失。

在"任务计划程序"界面中搜索LarkChannelBridge.Bot.前缀即可看到对应任务；status命令会解析任务的Last Result，0 表示上次运行成功。

多 profile：同时常驻 Claude 与 Codex 两个 bot 🤖

每个 profile 拥有独立的凭据、会话、工作目录、日志和独立的系统服务。想让 Claude 和 Codex 各跑一个 bot，分别启动即可：

lark-channel-bridge start --profile claude --agent claude lark-channel-bridge start --profile codex --agent codex

之后互不干扰地单独维护：

lark-channel-bridge restart --profile codex lark-channel-bridge status --profile codex

此外还有整机级的控制面选项start --web-ui：安装一个 supervisor 服务，单进程托管所有 profile 并提供本地 Web 控制台，适合多 bot 集中管理（src/cli/commands/start.ts）。

日常运维清单 📋

status会告诉你 bot 是否真正完成飞书握手——只有 WebSocket 连接成功后才算"在线"，避免"进程活着但 bot 掉线"的错觉。若start后 30 秒内没观察到连接，命令会直接给出日志路径提示。

常见问题排查 🔧

• stop 了 bot 又自己回来了：确认用的是stop（会自动关闭自启）而不是手动kill进程；旧的 plist / unit 仍带自启配置时，launchd/systemd会在下次登录把它拉回。
• 升级 Node 或 PATH 变更后 daemon 行为异常：重新执行一次start——它每次都会用当前 Node 二进制和 PATH 重新写入服务定义。
• bot 收发消息正常但 agent 不回复：通常是本地claude/codex未登录或会话目录失效，在飞书里发/status查看，/new重置会话常常就能解决。

更多细节可参考项目文档 README.zh.md 的"后台运行"章节。

小结

把 lark-coding-agent-bridge 交给操作系统托管，本质就三步：全局安装 →run完成首次扫码配置 →start注册后台服务。此后 launchd、systemd 和 Windows 计划任务会替你处理自启、崩溃恢复与日志落盘，bot 真正做到 7×24 小时稳定在线。配合多 profile 能力，一台机器可以同时常驻 Claude 与 Codex 两个助手，随时随地在飞书里派活。

【免费下载链接】lark-coding-agent-bridgeBot that bridges Feishu/Lark messenger with a local Claude Code or Codex CLI. Streaming cards, per-chat sessions, multiple workspaces项目地址: https://gitcode.com/gh_mirrors/fe/lark-coding-agent-bridge