codex_feishu_mcp_local

Feishu bot + MCP + Codex bridge workspace.

• 中文说明: README.zh-CN.md

Current Capabilities

• Direct plain text messages can go through Codex bridge without requiring a /codex prefix.
• Image messages can be downloaded from Feishu message resources and forwarded to the bridge as multimodal input.
• /codex is still supported for explicit bridge usage, along with /codex-reset, /codex-model, and /codex-dir.
• /clear clears both regular chat memory and bridge session state.

Layout

• SKILL.md: skill instructions for Codex
• agents/openai.yaml: skill UI metadata
• scripts/: operational PowerShell and shell scripts
• workspace/feishu_mcp_bot: Node.js Feishu bot project
• workspace/feishu_mcp_gui: Windows GUI controller for the bot
• workspace/output/lark-mcp-local-runtime: local MCP runtime package files
• references/: supporting docs copied from the working setup

Platform Support

• workspace/feishu_mcp_bot: intended to work on Windows and macOS/Linux
• scripts/*.ps1: Windows-first operational scripts
• scripts/*.sh: macOS/Linux operational scripts
• workspace/feishu_mcp_gui: Windows-only GUI based on github.com/lxn/walk

Quick Start

1. Copy workspace/feishu_mcp_bot/.env.example to workspace/feishu_mcp_bot/.env
2. Fill in your own Feishu and OpenAI credentials
3. Install dependencies in workspace/feishu_mcp_bot
4. Start the bot:

powershell -ExecutionPolicy Bypass -File ".\scripts\start-feishu-bot.ps1" -Restart

Or on macOS/Linux:

bash ./scripts/start-feishu-bot.sh --restart

5. Monitor health:

powershell -ExecutionPolicy Bypass -File ".\scripts\monitor-feishu-bot.ps1" -RunMcpHelpCheck

Or on macOS/Linux:

bash ./scripts/monitor-feishu-bot.sh --run-mcp-help-check

6. Build the GUI:

powershell -ExecutionPolicy Bypass -File ".\workspace\feishu_mcp_gui\build-feishu-gui.ps1"

The GUI is Windows-only. On macOS/Linux, use the shell scripts and the bot logs directly.

Feishu Bot Setup Guide

Use this sequence when configuring the bot in Feishu Open Platform:

1. Create a self-built application in Feishu Open Platform.
2. Enable the bot capability.
3. Configure the permissions required by this repository.
4. Set the OAuth redirect URL to http://localhost:3000/callback.
5. Choose the event subscription mode:
   • Feishu CN: prefer persistent connection
   • Lark global or public callback scenarios: use webhook
6. Subscribe at least to im.message.receive_v1.
7. Start the local bot before testing subscriptions.
8. Add the bot to a chat and send a message to verify the event path.

If you want image understanding:

• make sure your Feishu app has the permissions needed to read message resources
• make sure the model behind CODEX_BRIDGE_MODEL / CODEX_BRIDGE_BASE_URL supports image input

For webhook mode, configure the callback URL as:

http://<your_public_domain>/webhook/event

If you only need a quick minimum checklist, verify these four items first:

• bot capability is enabled
• required scopes are approved
• redirect URL is correct
• im.message.receive_v1 is subscribed

Pairing And Active Send

Approve a pending pairing:

powershell -ExecutionPolicy Bypass -File ".\scripts\approve-feishu-pairing.ps1" -Code YOUR_CODE -Remark 我

On macOS/Linux:

bash ./scripts/approve-feishu-pairing.sh --code YOUR_CODE --remark 我

Send a message to a bound recipient:

powershell -ExecutionPolicy Bypass -File ".\scripts\send-feishu-message.ps1" -Target 我 -Text "你好。"

On macOS/Linux:

bash ./scripts/send-feishu-message.sh --target 我 --text "你好。"

Notes

• workspace/feishu_mcp_bot/.env.example still keeps CODEX_WORKDIR and CODEX_WORKDIR_ROOTS as examples pointing to your own business workspace. Replace them with your own paths.
• The GUI and operational scripts are adjusted to use repository-relative defaults instead of machine-specific skill paths.
• The shell scripts assume bash, curl, node, ps, grep, lsof, and nohup are available in PATH.
• The shell scripts were added for macOS/Linux support, but were not end-to-end run against a live macOS environment in this Windows workspace.