relay

English | 简体中文

A Feishu bot that forwards chat messages to Codex and returns results in chat.

Warning

This project is currently in beta, and breaking changes may happen at any time.

Install

npm i @debbl/relay@latest -g

Prerequisites

1. Node.js 20+ and pnpm.
2. codex CLI installed and logged in (codex login).
3. Feishu app with bot capability enabled create-bot.
4. Feishu event subscription enabled for im.message.receive_v1.
5. Feishu bot permissions:
   • P2P messages to bot.
   • Group messages @ bot (or all group messages if you prefer).

Configuration

Relay reads configuration only from ~/.relay/config.json.

Run pnpm dev once to auto-generate a template file (the process exits after creation), then edit:

~/.relay/config.json

Config fields:

{
  "locale": "en",
  "env": {
    "BASE_DOMAIN": "https://open.feishu.cn",
    "APP_ID": "your_app_id",
    "APP_SECRET": "your_app_secret",
    "BOT_OPEN_ID": "ou_xxx",
    "CODEX_BIN": "codex",
    "CODEX_TIMEOUT_MS": null
  }
}

• Required fields (inside env): BASE_DOMAIN, APP_ID, APP_SECRET.
• Optional fields:
  • locale (root level, supported values: en, zh; default: en; unsupported value falls back to en with a warning).
  • BOT_OPEN_ID (empty or missing means disabled).
  • CODEX_BIN (default: codex).
  • CODEX_TIMEOUT_MS (default: no timeout; if set, must be a positive integer).

Run

cd <your_project>
relay

How To Use In Feishu

Message flow

1. Send a text message to the bot.
2. Bot replies immediately with a processing echo:
   • Received. Processing task: <task preview>
3. Bot sends final Codex result when done.
4. After /new, the first normal prompt is used directly as the session title (with normalization and truncation).

P2P chat

• Any text message is handled.

Group chat

• Bot only handles messages that @ the bot.
• Session is isolated by group + sender (different users in same group do not share context).

Commands

• /help show help.
• /new [default|plan] create a new conversation (default mode if omitted).
• /mode <default|plan> switch mode for current conversation.
• /status show current thread info.
• /projects show current fixed workspace root.
• /reset clear current conversation.

Notes

• Relay stores session index at ~/.relay/sessions.json and restores active sessions after restart.
• The index stores thread ids and basic metadata only; full session transcripts are in ~/.codex/sessions.
• Relay fixes workspace root to the process startup directory (process.cwd()).
• Relay checks npm for newer @debbl/relay versions at startup and prints a warning when an update is available.
• Set RELAY_SKIP_UPDATE_CHECK=1 to disable the startup update check.
• Ensure process user can read/write ~/.codex/sessions.
• Ensure process user can read/write ~/.relay/sessions.json.
• .env.local is no longer used for runtime config.

Quality checks

pnpm i18n:extract
pnpm lint
pnpm typecheck
pnpm test