Codex Feishu Monitor

Codex / Claude Code 任务监控 + 飞书机器人通知系统。

当服务器上的 AI 编程 Agent 完成任务、出错、或需要你继续指挥时，通过飞书机器人实时通知你。你也可以在飞书中发送指令（状态、日志、继续等）来控制 Agent。

---

目录结构

codex_feishu_monitor/
├── bot.py                    # 飞书长连接机器人服务（主进程）
├── monitor.py                # 状态 / 日志 / 任务队列维护模块
├── feishu_client.py          # 飞书 API 封装（token、发消息、回复）
├── config.py                 # 配置中心（环境变量读取）
├── requirements.txt          # Python 依赖
├── README.md                 # 本文件
├── scripts/
│   ├── codex_notify.py       # Codex notify/hook 调用入口
│   └── install_systemd.sh    # systemd 服务安装脚本
└── systemd/
    └── codex-feishu-bot.service  # systemd service 模板

---

快速开始

1. 安装依赖（使用 uv）

cd codex_feishu_monitor

# 创建虚拟环境
uv venv

# 安装依赖
uv pip install -r requirements.txt

或者使用传统 pip：

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. 配置环境变量

创建环境变量文件：

cat > ~/.feishu_codex_env <<'EOF'
export FEISHU_APP_ID="cli_xxxxxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export FEISHU_NOTIFY_CHAT_ID="oc_xxxxxxxxxxxxxxxx"  # 可选
EOF

变量	必填	说明
FEISHU_APP_ID	✅ 是	飞书应用的 App ID
FEISHU_APP_SECRET	✅ 是	飞书应用的 App Secret
FEISHU_NOTIFY_CHAT_ID	❌ 否	主动通知目标 chat_id，不填则只写本地文件

⚠️ 安全提醒：App Secret 是敏感信息，这个文件权限应设为 600：

chmod 600 ~/.feishu_codex_env

3. 启动测试

source ~/.feishu_codex_env
python bot.py

看到日志输出 BOT RUNNING (WebSocket long connection) 即表示启动成功。

---

飞书开放平台配置

在 飞书开放平台 中需要进行以下配置：

必需权限

在「权限管理」中添加：

• im:message — 获取消息内容
• im:message:send_as_bot — 以机器人身份发送消息
• im:message:read — 读取消息

事件订阅

在「事件订阅」中：

1. 开启 Bot 能力（如果尚未开启）
2. 订阅事件：im.message.receive_v1（接收消息）
3. 使用长连接模式（WebSocket）
4. 发布应用版本（配置修改后需要发布才能生效）

安全设置

• 不需要配置「请求地址 URL」（长连接模式不需要回调地址）
• 建议在「安全设置」中限制 IP 范围（如果你的服务器有固定 IP）

---

飞书消息指令

Bot 支持以下白名单指令（不会执行任何任意 shell 命令）：

指令	说明
状态	查看当前监控状态（任务状态、运行时间、待处理任务数）
日志	查看最近 50 行监控日志
继续 xxx	将指令写入任务队列（Agent 处理后才执行）
清除队列	清空待处理任务队列
帮助	显示帮助信息

⚠️ 安全设计：飞书消息不会直接执行任何 shell 命令。继续 xxx 只把指令写入队列文件，你需要另外编写脚本或 cron 来消费这个队列。

---

Codex / Claude Code 集成

方式 A：Codex notify 配置

在 ~/.codex/config.toml 中添加：

notify = ["python3", "/path/to/codex_feishu_monitor/scripts/codex_notify.py"]

Codex 在完成任务、出错、需要用户输入时会自动调用此脚本。

方式 B：Claude Code hooks 配置

在 ~/.claude/settings.json 中添加 hooks：

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "python3 /path/to/codex_feishu_monitor/scripts/codex_notify.py"
      }
    ]
  }
}

或使用 Claude Code config：

在 ~/.codex/config.toml 中：

[features]
hooks = true

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = "python3 /path/to/codex_feishu_monitor/scripts/codex_notify.py"
timeout = 30

notify 传参方式

脚本支持两种输入方式：

# 方式 1: 从 stdin 读取 JSON
echo '{"status":"done","summary":"task completed"}' | python3 scripts/codex_notify.py

# 方式 2: 从命令行参数读取 JSON
python3 scripts/codex_notify.py '{"status":"error","error":"connection failed"}'

---

systemd 服务安装

安装为用户服务（推荐，无需 sudo）

bash scripts/install_systemd.sh

安装后：

# 启用服务
systemctl --user enable codex-feishu-bot

# 启动服务
systemctl --user start codex-feishu-bot

# 查看状态
systemctl --user status codex-feishu-bot

# 查看日志
journalctl --user -u codex-feishu-bot -f

启用用户 lingering（让服务在登出后继续运行）

loginctl enable-linger

安装为系统服务（需 sudo）

bash scripts/install_systemd.sh --system

---

数据文件

所有运行时数据默认存储在 ~/.codex_feishu_monitor/ 下，也可以通过 CODEX_FEISHU_BASE_DIR 环境变量覆盖：

export CODEX_FEISHU_BASE_DIR="$HOME/.codex_feishu_monitor"

文件	说明
status.json	当前监控状态
monitor.log	监控日志
task_queue.txt	待处理任务队列

status.json 格式：

{
  "last_status": "done",
  "last_update_time": "2026-06-14 15:30:00",
  "last_summary": "Fixed login bug",
  "last_error": ""
}

状态值：idle | running | done | error | waiting_user

---

消费任务队列

继续 xxx 指令写入队列后，你可以用 cron 或脚本消费：

#!/bin/bash
# 示例：每 30 秒检查一次队列
QUEUE_FILE="${CODEX_FEISHU_BASE_DIR:-$HOME/.codex_feishu_monitor}/task_queue.txt"
if [[ -f "$QUEUE_FILE" && -s "$QUEUE_FILE" ]]; then
    # 处理任务...
    cat "$QUEUE_FILE"
    > "$QUEUE_FILE"  # 清空队列
fi

---

安全特性

• ✅ App Secret 从环境变量读取，不写死在代码中
• ✅ 日志中不打印完整 App Secret（只显示前 4 位和后 4 位）
• ✅ 飞书消息使用白名单机制，不执行任意 shell 命令
• ✅ 继续 xxx 只写入队列文件，不直接执行
• ✅ README 示例使用占位符，不含真实密钥
• ✅ 环境变量文件建议权限 600

---

故障排查

Bot 无法启动：

# 检查环境变量是否加载
source ~/.feishu_codex_env
echo $FEISHU_APP_ID

# 检查依赖是否安装
python3 -c "import lark_oapi; print(lark_oapi.__version__)"

Bot 收不到消息：

1. 确认飞书应用已发布
2. 确认已订阅 im.message.receive_v1 事件
3. 确认在飞书中向机器人发送的是 私聊消息 或将机器人 加入群聊
4. 查看 Bot 日志：tail -f ${CODEX_FEISHU_BASE_DIR:-$HOME/.codex_feishu_monitor}/monitor.log

notify 不发飞书消息：

• 确认 FEISHU_NOTIFY_CHAT_ID 已设置
• 获取 chat_id：在飞书中向机器人发一条消息，从 API 日志中提取