[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81290":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":28,"lastSyncTime":29,"discoverSource":30},81290,"feishu-codex-bridge","QQQingyu\u002Ffeishu-codex-bridge","QQQingyu","Run local Codex CLI from Feishu\u002FLark chat, with sessions, attachments, and background service support.",null,"TypeScript",200,9,5,1,0,12,96,152,71,93,"MIT License",false,"main",[],"2026-06-12 04:01:32","# feishu-codex-bridge\n\nA local Feishu \u002F Lark bot for calling Codex CLI from chat. You send a message in Feishu \u002F Lark; the bridge runs `codex exec` on your machine and streams the result back to chat.\n\nThis project is built with reference to [zarazhangrui\u002Ffeishu-claude-code-bridge](https:\u002F\u002Fgithub.com\u002Fzarazhangrui\u002Ffeishu-claude-code-bridge), with thanks for the original design and implementation.\n\n[中文 README](.\u002FREADME.zh.md)\n\n## Requirements\n\nYou need:\n\n- Node.js >= 20\n- A local terminal for QR scan, install prompts, and `codex login`\n- Network access to npm registry, OpenAI \u002F Codex, and the Feishu \u002F Lark open platform\n\nYou do not need to preinstall `codex` or `lark-cli`. When missing, the bridge installs them into private directories to avoid global npm permission issues:\n\n```bash\n~\u002F.feishu-codex-bridge\u002Fcodex-cli\n~\u002F.feishu-codex-bridge\u002Flark-cli\n```\n\nIf Codex is installed as a macOS app but `codex` is not in `PATH`, the bridge also checks:\n\n```bash\n\u002FApplications\u002FCodex.app\u002FContents\u002FResources\u002Fcodex\n```\n\nYou can pin a custom binary explicitly:\n\n```bash\nexport CODEX_BIN=\"\u002Fpath\u002Fto\u002Fcodex\"\n```\n\n## Install\n\n```bash\nnpm i -g feishu-codex-bridge\nfeishu-codex-bridge --version\n```\n\n## First-Time Setup\n\nRun in a local terminal:\n\n```bash\nfeishu-codex-bridge start\n```\n\nOn first run, it guides you through:\n\n1. Find Codex CLI from `CODEX_BIN`, `PATH`, the bridge private install, or macOS `Codex.app`; if missing, ask to install `@openai\u002Fcodex`.\n2. Check Codex login status; if needed, run `codex login`.\n3. Show a QR code for Feishu \u002F Lark scan.\n4. Create or select a PersonalAgent app.\n5. Save app config and move the App Secret into a local encrypted keystore.\n6. Check `lark-cli`; if missing, ask to install it into the private directory.\n7. Initialize `lark-cli` with the same App ID.\n\nAfter the terminal prints that it is listening, DM the bot:\n\n```text\n\u002Fstatus\nHelp me inspect this repo\n```\n\n`\u002Fstatus` is a chat-side health check. It shows the current cwd, Codex session, active agent, and reasoning effort. Regular messages are sent to Codex.\n\nIn groups and topic groups, the default policy is to respond only when mentioned.\n\nFor service mode, complete this step first; see [Background Service](#background-service).\n\n## Platform Settings\n\nThe QR wizard can create the app shell, but you still need to confirm scopes and events in the developer console. Without these settings, the bridge may connect successfully while the bot still cannot receive messages or send replies.\n\nPermission scopes:\n\n- `im:message`\n- `im:message:send_as_bot`\n- `im:resource`\n- `im:chat`, required for group creation\n- `drive:drive`, required for cloud-doc comments\n\nEvent subscriptions, long-connection mode:\n\n- `im.message.receive_v1`\n- `card.action.trigger`\n- `drive.notice.comment_add_v1`, required for cloud-doc `@bot` comments\n- `im.message.reaction.created_v1` \u002F `deleted_v1`, optional\n- `im.chat.member.bot.added_v1`, optional\n\nThe bridge and `lark-cli` must use the same Feishu \u002F Lark app. Do not run this for `lark-cli`:\n\n```bash\nlark-cli config init --new\n```\n\nOtherwise bot messages, API permissions, and OAuth identities are split across apps and become hard to debug.\n\n## Background Service\n\nComplete one foreground setup first. After the terminal is listening and `\u002Fstatus` works in chat, press `Ctrl+C` to stop the foreground process, then install the macOS `launchd` service:\n\n```bash\nfeishu-codex-bridge service install launchd\nfeishu-codex-bridge service status\nfeishu-codex-bridge service logs --follow\n```\n\nRunning two bridge processes for the same Feishu \u002F Lark app causes unreliable event delivery. Stop the foreground process before installing the service.\n\nRestart or uninstall:\n\n```bash\nfeishu-codex-bridge service restart\nfeishu-codex-bridge service uninstall\n```\n\nService logs:\n\n- `~\u002F.feishu-codex-bridge\u002Fservice.log`\n- `~\u002F.feishu-codex-bridge\u002Fservice.err.log`\n\n## Daily Use\n\nThe bridge keeps a local long-lived bot process and turns each chat message into a local Codex run:\n\n```text\nFeishu\u002FLark chat\n  -> bridge WebSocket\n  -> local codex exec \u002F resume\n  -> optional lark-cli calls\n  -> streaming card \u002F text reply\n```\n\nResponsibilities are split:\n\n- **bridge** receives events, maps chats to sessions, downloads attachments, renders cards, and keeps the bot alive.\n- **Codex CLI** reasons, edits files, runs commands, and resumes Codex sessions.\n- **Lark CLI** gives Codex a practical API tool for messages, docs, calendars, groups, OAuth, and other Lark resources.\n\nCommon chat commands:\n\n| Command | Effect |\n|---|---|\n| \u003Ccode>\u002Fstatus\u003C\u002Fcode> | Show cwd, session, agent, and reasoning effort |\n| \u003Ccode>\u002Fnew\u003C\u002Fcode> \u002F \u003Ccode>\u002Freset\u003C\u002Fcode> | Reset the current chat’s Codex session |\n| \u003Ccode>\u002Fresume [N]\u003C\u002Fcode> | List and resume recent Codex sessions under the current cwd |\n| \u003Ccode>\u002Fcd <path>\u003C\u002Fcode> | Change cwd for the current chat and reset the session |\n| \u003Ccode>\u002Fws list\u002Fsave\u002Fuse\u002Fremove\u003C\u002Fcode> | Manage named workspaces |\n| \u003Ccode>\u002Fconfig\u003C\u002Fcode> | Adjust reply mode, tools, concurrency, timeout, reasoning effort, access control |\n| \u003Ccode>\u002Ftimeout [N|off|default]\u003C\u002Fcode> | Override idle timeout for the current session |\n| \u003Ccode>\u002Fstop\u003C\u002Fcode> | Stop the current Codex run |\n| \u003Ccode>\u002Fps\u003C\u002Fcode> | List bridge processes on this host |\n| \u003Ccode>\u002Fexit <id|#>\u003C\u002Fcode> | Stop a bridge process |\n| \u003Ccode>\u002Freconnect\u003C\u002Fcode> | Reconnect the Feishu \u002F Lark WebSocket |\n| \u003Ccode>\u002Fdoctor [description]\u003C\u002Fcode> | Ask Codex to diagnose recent bridge logs |\n| \u003Ccode>\u002Faccount\u003C\u002Fcode> | View or change the Feishu \u002F Lark app used by the bridge |\n| \u003Ccode>\u002Fhelp\u003C\u002Fcode> | Show the help card |\n\n## User OAuth\n\nBasic chat does not require user OAuth. You only need it when Codex must access personal resources such as your own chat history, docs, or calendar:\n\n```bash\nexport PATH=\"$HOME\u002F.feishu-codex-bridge\u002Flark-cli\u002Fnode_modules\u002F.bin:$PATH\"\nlark-cli auth login --recommend\n```\n\nBot identity being ready does not mean user OAuth is complete. Tenant\u002Fbot APIs can work with bot identity; personal resources usually require user OAuth.\n\n## Develop From Source\n\nThe npm package already contains `dist\u002F` and can run directly. A fresh clone needs dependencies and a build first:\n\n```bash\nnpx pnpm@10.20.0 install\nnpx pnpm@10.20.0 build\nnode bin\u002Ffeishu-codex-bridge.mjs --help\n```\n\nCommon checks:\n\n```bash\nnpx pnpm@10.20.0 typecheck\nnpx pnpm@10.20.0 test\n```\n\n## Configuration Files\n\n| Path | Purpose |\n|---|---|\n| `~\u002F.feishu-codex-bridge\u002Fconfig.json` | Bridge app config and preferences |\n| `~\u002F.feishu-codex-bridge\u002Fsecrets.enc` | Encrypted App Secret store |\n| `~\u002F.feishu-codex-bridge\u002Fsessions.json` | Chat\u002Ftopic to Codex session mapping |\n| `~\u002F.feishu-codex-bridge\u002Fworkspaces.json` | Named workspaces |\n| `~\u002F.feishu-codex-bridge\u002Fprocesses.json` | Live bridge process registry |\n| `~\u002F.feishu-codex-bridge\u002Fcodex-cli\u002F` | Bridge-managed private Codex CLI install |\n| `~\u002F.feishu-codex-bridge\u002Flark-cli\u002F` | Bridge-managed private Lark CLI install |\n| `~\u002F.feishu-codex-bridge\u002Flogs\u002FYYYY-MM-DD.log` | Structured runtime logs |\n| `~\u002F.feishu-codex-bridge\u002Fmedia\u002F\u003CchatId>\u002F` | Downloaded image\u002Ffile cache, cleaned after 24h |\n\n### Codex Reasoning Effort\n\nBy default the bridge does not override Codex CLI reasoning effort. Codex inherits `model_reasoning_effort` from `~\u002F.codex\u002Fconfig.toml`.\n\nTo pin it for bridge runs only, use `\u002Fconfig` in Feishu \u002F Lark or edit:\n\n```json\n{\n  \"preferences\": {\n    \"codexReasoningEffort\": \"xhigh\"\n  }\n}\n```\n\nAllowed values: `minimal`, `low`, `medium`, `high`, `xhigh`. Remove the field, or select default in `\u002Fconfig`, to inherit the global Codex config again.\n\n### Access Control\n\nThe default mode is open: anyone who can find the bot can DM it, and group users can mention it. Tighten this in `\u002Fconfig`:\n\n- `allowedUsers`: open_id allowlist for interacting with the bot.\n- `allowedChats`: group chat_id allowlist; DMs are not restricted by this field.\n- `admins`: users allowed to run sensitive commands such as `\u002Faccount`, `\u002Fconfig`, `\u002Fexit`, `\u002Freconnect`, `\u002Fdoctor`, `\u002Fcd`, and `\u002Fws`.\n\nFind IDs from logs:\n\n```bash\ngrep '\"event\":\"enter\"' ~\u002F.feishu-codex-bridge\u002Flogs\u002F$(date +%Y-%m-%d).log | tail -5\n```\n\n## Common Fixes\n\n**Bot is silent**\n\nCheck process and service state:\n\n```bash\nfeishu-codex-bridge ps\nfeishu-codex-bridge service status\n```\n\nFollow logs:\n\n```bash\nfeishu-codex-bridge service logs --follow\n```\n\nIf the bridge is connected but chat is silent, check open-platform scopes and event subscriptions first.\n\n**Codex CLI is missing or not logged in**\n\n```bash\nfeishu-codex-bridge doctor\n```\n\nIf needed, rerun foreground setup:\n\n```bash\nfeishu-codex-bridge start\n```\n\n**Codex cannot find `lark-cli`**\n\n```bash\nfeishu-codex-bridge doctor\n```\n\nFor direct terminal usage:\n\n```bash\nexport PATH=\"$HOME\u002F.feishu-codex-bridge\u002Flark-cli\u002Fnode_modules\u002F.bin:$PATH\"\n```\n\n**`lark-cli` App ID differs from the bridge App ID**\n\nRerun foreground setup:\n\n```bash\nfeishu-codex-bridge start\n```\n\nAccept the prompt to switch `lark-cli` back to the bridge app. Do not run `lark-cli config init --new`.\n\n**Codex run hangs**\n\nSend `\u002Fstop` in chat. For recurring hangs, set a global idle timeout in `\u002Fconfig`, or set one for the current session:\n\n```text\n\u002Ftimeout 10\n```\n\n## License\n\n[MIT](.\u002FLICENSE)\n","feishu-codex-bridge 是一个通过飞书\u002FLark 聊天界面调用本地 Codex CLI 的工具。它支持会话、附件以及后台服务，用户可以在聊天中发送消息，该工具会在本地运行 `codex exec` 并将结果实时返回到聊天中。项目采用 TypeScript 编写，具有良好的可维护性和扩展性。它适用于需要在团队协作环境中快速获取代码执行结果的场景，如开发讨论、代码审查等。安装和配置过程简单直观，无需预先安装 Codex 或 Lark CLI，工具会在首次运行时自动处理这些依赖，并且能够检查和使用 macOS 应用中的 Codex 二进制文件。此外，它还支持自定义二进制路径设置，提供了较高的灵活性。",2,"2026-06-11 04:04:30","CREATED_QUERY"]