ChatCCC

飞书（Lark）聊天控制 Claude Code / Cursor / Codex

解决的核心痛点

传统的 Claude Code（尤其是使用第三方 API 的，如 DeepSeek），需要坐在电脑桌前才能用。离开电脑就没法用了。

ChatCCC 把 Claude Code、Cursor Agent、Codex (OpenAI) 接入了飞书群聊：

• 手机上也能用 Claude Code / Cursor / Codex —— 在飞书群里发消息就等于在终端输入指令，AI 的思考和回复会流式展示在群卡片里
• 多会话并行 —— 一个群就是一个 AI 会话，完全隔离、互不干扰，并行工作效率更高
• 多工具切换 —— /new 使用默认 Agent 创建会话，也可用 /new claude、/new cursor、/new codex 指定工具，各取所长

一句话：在任何设备上打开飞书，就能让 Claude Code / Cursor / Codex 帮你写代码、排查问题、分析项目。

为什么选 ChatCCC

• 一群一会话，心智最简单 —— /new 直接建一个新飞书群，群本身就是 AI 会话上下文。换会话就是换群，没有 thread / 子话题概念，手机端切换最直观
• 零配置成本 —— 单一 config.json，没有 TOML 也没有零散环境变量。npm i -g chatccc 后任意目录直接 chatccc 就跑，首次启动自动弹出本地 Web 配置向导
• 群里能跑 git —— /git status、/git pull、/git log 在飞书群里直接执行 stdout/stderr 回发，不用回电脑
• 代码极简易改 —— 纯 TypeScript 实现，核心只有 20 多个文件，统一 ToolAdapter 接口屏蔽 Claude / Cursor / Codex 差异，看得懂、改得动

怎么部署

1. 安装

npm 全局安装（推荐）

npm install -g chatccc

要求 Node.js >= 20。安装完成后，在任意目录直接启动即可：

chatccc

ChatCCC 的所有数据（config.json、logs/、state/）都保存在 npm 包安装目录下，与你当前终端所在目录无关。不需要先 cd 到任何特定目录。

首次启动时若 config.json 还没有有效凭证，会自动起一个本地 Web 配置向导（默认 http://127.0.0.1:18080），用浏览器把飞书 App ID / App Secret 等填进去，保存即开始运行。

已在运行的实例，启动完成后控制台底部 banner 也会打印「配置面板」地址，随时可以打开浏览器查看状态、修改配置（多数改动无需重启即可生效）。停止 / 重启请通过页面顶部按钮或终端 Ctrl+C，面板上不再提供"启动"按钮——服务停止后页面随进程退出，需要回到终端重新执行 chatccc。

从源码安装

git clone https://github.com/wzj998/ChatCCC.git
cd ChatCCC
npm install
npm run dev

启动后机器人通过 WebSocket 连接飞书服务器，日志会写入仓库根目录下的 logs/。

Cursor Agent CLI（使用 Cursor 会话时需要）

ChatCCC 不捆绑 Cursor Agent CLI，需要用户自行安装。

推荐安装方式（Windows）：

在 PowerShell 中执行：

irm 'https://cursor.com/install?win32=true' | iex

安装完成后 agent 命令会出现在系统 PATH 中。

其他安装方式：

1. Cursor IDE 自带：安装 Cursor IDE 后，部分版本会自带 agent 或 cursor-agent 命令
2. 独立安装：Cursor 正在逐步提供独立的 CLI 安装方式

安装后需登录 Cursor 账号：

agent login

验证是否已安装（任一可用即可）：

agent --version
cursor-agent --version

ChatCCC 启动时会按以下顺序确定 Cursor Agent CLI：

1. config.json 中的 cursor.path 指定的路径（若已配置）
2. Windows 上 Cursor IDE 默认安装位置 %LOCALAPPDATA%\cursor-agent\agent.cmd（自动识别）
3. PATH 中的 agent 命令

首次启动 ChatCCC 时，如果 config.json 不存在，会从 config.sample.json 复制一份并立即探测一次 Cursor / Codex CLI 的绝对路径，命中就写入 cursor.path / codex.path，无须手动编辑。

若想强制使用某个非默认的可执行文件（例如 cursor-agent 而不是 agent），可在 config.json 中显式指定：

{
  "cursor": {
    "path": "/path/to/agent"
  }
}

旧版字段 cursor.command 仍可读取（启动时会打印一次 warning 提示改名），新配置请统一使用 cursor.path。

说明：只使用 Claude Code（/new claude，或把 Claude Code 设为默认 Agent 后使用 /new）的用户无需安装 Cursor CLI。

Codex CLI（使用 Codex 会话时需要）

ChatCCC 不捆绑 Codex CLI，需要用户自行安装：

npm install -g @openai/codex

安装后需登录 OpenAI 账号：

codex login

验证是否已安装：

codex --version

Codex 会话的模型和努力程度由 config.toml（~/.codex/config.toml）决定，也可在 config.json 中显式覆盖：

{
  "codex": {
    "path": "",
    "model": "",
    "effort": ""
  }
}

• codex.path：留空时直接调用 PATH 中的 codex；可填绝对路径指向自定义可执行文件（首次创建 config.json 时会自动探测并填入）
• codex.model：留空时由 ~/.codex/config.toml 决定
• codex.effort：留空时由 ~/.codex/config.toml 决定（通过 -c model_reasoning_effort 传递）

旧版字段 codex.command 仍可读取（启动时会打印一次 warning 提示改名），新配置请统一使用 codex.path。

说明：只使用 Claude Code 或 Cursor 的用户无需安装 Codex CLI。

2. 创建飞书应用

打开 飞书开放平台，创建一个企业自建应用。

第一步：同时使用公司飞书和个人飞书

如果你所在的公司也使用飞书，请看此步骤；否则请直接跳到第二步。

如果你既要在公司飞书中使用 ChatCCC，又想用个人飞书账号，推荐以下方案：

方案一：安卓手机

使用系统的「应用双开」功能，把飞书复制一份。原版飞书登录公司账号，飞书复制版登录个人飞书账号，两个飞书可以同时在线、互不干扰。

方案二：苹果手机

在 App Store 下载「飞书国际版（Lark）」。原版飞书登录公司账号，Lark 登录个人飞书账号，两个 App 互相独立、可同时在线。

第二步：添加机器人（千万别忘！）

创建应用后，立刻在「应用功能」中开启「机器人」能力。没有机器人，就根本找不到哪里和这个机器人对话，整个 ChatCCC 无法工作。

权限配置（重要）（在「权限管理」中按前缀搜索，将以下两类前缀开头的权限全部开通）：

控制台中同一前缀下往往有多条子权限，请逐项勾选开通，避免遗漏导致收不到消息或卡片异常。

事件订阅（重要）（在「事件与回调」中）：订阅 im.message.receive_v1 和 card.action.trigger 事件。

发布版本（不要忘了）：配置完成后创建应用版本并发布（仅企业内部可用即可）。

3. 获取凭证

在飞书应用详情页的「凭证与基础信息」中，复制 App ID 和 App Secret。

4. 配置 config.json

ChatCCC 的所有运行参数都集中在包根目录的 config.json。

推荐：用 Web 配置向导（首次启动自动弹出）

第一次运行 chatccc 时，如果 config.json 还没有有效凭证，会自动起一个本地 Web 服务（默认 http://127.0.0.1:18080）。在浏览器里把上一步拿到的 App ID / App Secret 等填进去，保存即写入 config.json，进程立即继续启动飞书 WebSocket。

备选：手动编辑 config.json

config.json 不存在时，ChatCCC 会从 config.sample.json 复制一份，结构如下：

{
  "feishu": {
    "appId": "cli_xxxxxxxxxxxx",
    "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "port": 18080,
  "gitTimeoutSeconds": 180,
  "claude": {
    "enabled": false,
    "defaultAgent": true,
    "model": "",
    "effort": "",
    "apiKey": "",
    "baseUrl": ""
  },
  "cursor": {
    "enabled": false,
    "defaultAgent": false,
    "path": "",
    "model": ""
  },
  "codex": {
    "enabled": false,
    "defaultAgent": false,
    "path": "",
    "model": "",
    "effort": ""
  }
}

各字段含义：

claude.model / claude.effort 的旧值 "default" 仍兼容，启动时会按留空处理并打印一次 warning，请尽快改成 ""。

cursor.path / codex.path 由首次启动时的自动探测填入，一般无需手动修改。

第三方 API（如 DeepSeek）：填 claude.apiKey 与 claude.baseUrl

若你通过 Anthropic 兼容网关（例如 DeepSeek 的 /anthropic 端点）调用模型，需要把网关凭证填到 config.json 的 claude.apiKey 与 claude.baseUrl。官方 Claude 用户（本机已通过 claude CLI 完成 OAuth 登录）保持这两项 "" 即可，无需任何额外配置。

两条等价的填写路径：

1. Web 配置向导（推荐）

打开 http://127.0.0.1:18080（首次启动自动弹出，已在运行的实例也可手动访问），在「Claude Agent」一节顶部把「API 来源」从 官方 API（Anthropic 直连） 切换到 第三方 API（自定义网关）——切换后会出现 API Key / Base URL 两个输入框，填进去保存即可。切回官方模式后保存，已填的密钥会被自动清空，不会残留在 config.json 中。

2. 直接编辑 config.json

{
  "claude": {
    "model": "",
    "effort": "",
    "apiKey": "你的_API_密钥",
    "baseUrl": "https://api.deepseek.com/anthropic"
  }
}

ChatCCC 不会把这两个值写入主进程的环境变量；它们仅在调用 Claude Agent SDK 时被注入到 SDK 拉起的子进程，跟主进程 env 完全隔离。两项留空 / 缺失时，子进程沿用主进程默认的鉴权行为（即官方 Claude 的 OAuth）。

所有运行参数（端口、/git 超时、各 AI 工具模型 / 路径等）都在第 4 节展示的 config.json 里配置，不再使用 CHATCCC_* 环境变量。多实例共存只需在每个实例的 config.json 里把 port 设为不同值即可（例如 18080 / 18081），ChatCCC 启动时会自动清理各自端口上的旧进程。

权限说明：目前 ChatCCC 以 bypassPermissions 模式运行，即跳过所有权限确认、允许所有操作。后续会考虑引入细粒度权限控制，让你可以按需放行特定操作。

Linux 用户注意：不能将项目装在 /root 目录下运行。

5. 开始使用

在飞书中找到你的机器人，发送 /new（使用 config.json 中 defaultAgent: true 的默认 Agent）或 /new claude / /new cursor / /new codex，机器人会自动创建一个群聊并把 AI 会话绑定到该群。之后直接在群里发消息就能对话。

可用指令

技术栈

TypeScript / Node.js >= 20 / tsx / Anthropic Claude Agent SDK / Cursor Agent CLI / Codex CLI (OpenAI) / 飞书 WebSocket API / CardKit