CodeClaw

中文文档 | English

通过飞书远程控制本地 AI CLI，在手机或任何安装了飞书的设备上继续处理代码、排查问题和恢复上下文。

CodeClaw 当前支持把飞书机器人接到本地的 Claude Code CLI、Codex CLI、Droid CLI，并提供会话持久化、任务恢复、目录切换、后端切换、流式进度展示与变更记录能力。

功能概览

• 飞书私聊 / 群聊驱动本地 AI CLI
• 支持 Claude / Codex / Droid 三种后端
• 流式进度消息，持续更新执行状态
• 会话、目录、后端设置按聊天持久化
• 任务列表与恢复能力，可回到旧会话
• 新建会话与彻底清空历史分离
• 可选 Git / 飞书文档 / 控制台变更记录
• 支持权限模式、sandbox、approval、autonomy、spec 等控制项

效果预览

实时流式进度更新

交互式帮助卡片

环境要求

• Node.js >= 18
• 飞书开发者账号与自建机器人应用
• 至少安装一个本地 CLI：
  • Claude Code CLI
  • Codex CLI
  • Droid CLI

安装

git clone https://github.com/MichaelWayneLIU/CodeClaw.git
cd codeclaw
npm install

配置

先复制环境变量模板：

cp .env.example .env

.env.example 中当前支持的核心配置如下：

# 飞书
FEISHU_APP_ID=
FEISHU_APP_SECRET=
FEISHU_ENCRYPT_KEY=
FEISHU_VERIFICATION_TOKEN=
FEISHU_DOMAIN=feishu
FEISHU_ALLOWED_USER_OPEN_IDS=
FEISHU_ALLOWED_CHAT_IDS=
FEISHU_ADMIN_USER_OPEN_IDS=

# Provider
DEFAULT_PROVIDER=claude
PROVIDER_ALLOWED=claude,codex,droid

# Claude
ANTHROPIC_API_KEY=
CLAUDE_CODE_PATH=
CLAUDE_DEFAULT_MODEL=
CLAUDE_ALLOW_BYPASS_PERMISSIONS=false
CLAUDE_ALLOWED_WORKING_DIRECTORIES=

# Codex
CODEX_ENABLED=true
CODEX_CLI_PATH=
CODEX_DEFAULT_MODEL=

# Droid
DROID_ENABLED=true
DROID_CLI_PATH=
DROID_DEFAULT_MODEL=

# Server
HOST=127.0.0.1
PORT=3000

# Session
SESSION_TIMEOUT_MINUTES=30
MAX_HISTORY_LENGTH=50

# Logging
LOG_LEVEL=info

说明：

• PROVIDER_ALLOWED 用于限制可切换的后端列表
• FEISHU_ALLOWED_USER_OPEN_IDS / FEISHU_ALLOWED_CHAT_IDS 可限制访问范围
• FEISHU_ADMIN_USER_OPEN_IDS 用于限制高风险模式切换
• CLAUDE_ALLOWED_WORKING_DIRECTORIES 留空时默认仅允许启动目录

飞书应用配置

1. 在飞书开放平台创建企业自建应用
2. 开启机器人能力
3. 订阅事件：
   • im.message.receive_v1
   • card.action.trigger
4. 申请权限（可直接导入 imgs/feishu-permissions.json）
5. 将应用发布到企业内部可用范围

常用权限包括：

• im:message
• im:message:send_as_bot
• im:message.group_at_msg:readonly
• im:chat
• im:chat.members:bot_access
• cardkit:card:write

启动方式

npm run build
npm start

开发模式：

npm run dev

也可以直接使用 CLI：

codeclaw start
codeclaw start claude
codeclaw start codex /path/to/project
codeclaw check
codeclaw config
codeclaw help

CLI 子命令与当前实现一致：

• start [provider] [directory] 启动服务
• check 检查所有已启用 CLI 是否可用
• config 打印当前配置
• help 显示帮助

在飞书中的使用方式

基本交互

私聊机器人直接发送消息即可；群聊中需要先 @机器人。

例如：

读取 package.json 并说明项目结构

@机器人 帮我检查这个目录里的测试失败原因

会话与控制命令

命令	说明
? ？ /help	显示帮助卡片
/clear /reset	清空当前会话上下文和历史任务
/newsession /new	新建会话，但保留历史任务，后续可恢复
/status	查看当前会话状态
/pwd	查看当前工作目录
/ls /dir	列出当前目录内容
/cd <路径>	切换工作目录，并清空当前会话上下文
/provider <claude|codex|droid>	切换当前会话后端，并清空当前会话上下文
/tasklist /tasks	查看当前聊天下的历史任务列表
/resume <目录>	恢复指定目录对应的历史任务
/taskdelete <目录>	删除指定目录对应的任务记录

模式相关命令

Claude：

• /mode <default|acceptEdits|plan|bypassPermissions>

Codex：

• /sandbox <read-only|workspace-write|danger-full-access>
• /approval <on-request|full-auto|bypass>

Droid：

• /auto <read-only|low|medium|high>
• /permissions <normal|unsafe>
• /spec <on|off>

说明：

• 高风险模式通常应仅开放给管理员用户
• 帮助卡片内可直接点击按钮切换目录、查看任务、切换后端、查看状态、新建会话或清空历史

当前行为说明

• 会话以聊天为维度维护
• 工作目录、后端、模式设置会持久化保存到 data/
• 当当前目录与当前后端存在历史任务时，会尝试自动命中最近一次 provider 会话
• /newsession 只重建当前会话，不删除历史任务
• /clear 会同时关闭当前会话并删除该聊天下的历史任务
• 会话超时后会自动过期

变更记录

项目内置变更记录器，支持：

• git
• feishu-doc
• console
• none

配置文件位于：

data/change-logger-config.json

示例：

{
  "enabled": true,
  "type": "git",
  "git": {
    "autoCommit": false,
    "commitMessageTemplate": "feat(codeclaw): {userMessage}",
    "includeDiff": true,
    "excludePatterns": ["node_modules", ".git", "dist"]
  }
}

项目结构

当前 src/ 目录的主要结构如下：

src/
├── app.ts
├── cli.ts
├── index.ts
├── change-logger/
├── feishu/
├── providers/
├── session/
├── types/
└── utils/

其中：

• src/app.ts：应用主流程与命令分发
• src/cli.ts：CLI 入口
• src/feishu/：飞书客户端与事件处理
• src/providers/：Claude / Codex / Droid provider 封装
• src/session/：会话管理、任务存储、目录历史
• src/change-logger/：变更记录后端
• src/utils/：配置、日志、卡片与消息格式化

开发

npm install
npm run build
npm test
npm run lint

安全注意事项

• 不要直接暴露到公网
• 谨慎开放高风险模式：bypassPermissions、danger-full-access、bypass、unsafe
• 用 CLAUDE_ALLOWED_WORKING_DIRECTORIES 限制可操作目录范围
• 使用 FEISHU_ALLOWED_USER_OPEN_IDS / FEISHU_ALLOWED_CHAT_IDS 限制访问对象

致谢

本项目在思路与实现上受原始项目启发，特别感谢：

• Hanson/claude-client

许可证

MIT，详见 LICENSE