Claude、Codex 接入飞书：cc-connect 安装、授权与排障指南

如果你已经把 Claude Code 或 Codex CLI 装在电脑上，却只能坐在电脑前输入命令，那其实还差了一层：把本地 Agent 接到你每天会打开的聊天平台里。

我更推荐把这件事理解成“消息入口改造”，而不是“给 AI 换个聊天窗口”。代码和命令仍然跑在本地，飞书只是负责收发消息，cc-connect 负责把两边接起来。

先给结论：当前 cc-connect 文档支持把本地 Claude Code、Codex 等 Agent 接到飞书/Lark，也提供个人微信 Weixin/ilink 和企业微信 WeCom 等不同通道。它是第三方桥接项目，不是 Anthropic、OpenAI、飞书或微信官方产品。安装前要先确认 CLI 能单独登录，接入后还要检查权限、发布状态和消息回路。

一、先把这条链路想明白

完整链路大致是：

飞书或其他聊天平台
        ↓
cc-connect 平台适配层
        ↓
本地 Claude Code / Codex CLI
        ↓
你的工作目录、命令和项目文件

所以它不是把代码上传到某个陌生网页上运行，而是让本地 Agent 多了一个消息入口。也正因为如此，工作目录、终端权限和运行模式比“能不能扫码”更值得认真检查。

cc-connect 的一个项目通常绑定三样东西：一个项目名称、一个 Agent 和一个工作目录；随后再给这个项目挂上飞书、微信或其他平台。一个进程可以管理多个项目，但不同项目最好使用不同目录和权限，不要把所有东西都指向同一个家目录。

二、安装顺序不要反

很多人第一次接入失败，不是命令写错，而是顺序反了。建议按下面的顺序处理：

先装 Agent CLI
→ 让 Agent CLI 单独完成登录
→ 安装 cc-connect
→ 创建项目和平台配置
→ 启动服务
→ 用消息和日志双重验证

1. 先确认 Claude Code 或 Codex CLI

Claude Code 和 Codex 的安装方式、登录方式会随官方版本变化，建议从各自官方文档进入。项目 README 给出的示例包括：

# Claude Code：选择官方文档或当前适用的安装方式
# 安装完成后先确认：
claude --version

# Codex CLI：
# npm install -g @openai/codex
codex --version

版本命令能正常返回还不够。分别运行一次 claude 或 codex，完成自己的官方登录流程，确认它们能在本地独立回答一个简单问题。

2. 安装 cc-connect

当前项目文档列出的常见方式是 npm、Homebrew、Release 二进制或源码编译。以 npm 为例：

npm install -g cc-connect
cc-connect --version

如果你使用 Homebrew 或 Release 文件，也要以当前仓库 README 为准。不要把文章中的版本号当成永久版本号。

三、用安装向导创建项目

当前项目提供 AI Agent 引导和手动安装两条路径。想少改配置文件，可以先把项目的安装文档交给已经登录的 Agent；想知道每一步发生了什么，则直接使用命令和 Web 管理界面。

方式 A：让 Agent 读取安装文档

项目 README 当前给出的思路是把安装文档地址交给 Claude Code 或其他 Agent：

Follow https://raw.githubusercontent.com/chenhg5/cc-connect/refs/heads/main/INSTALL.md to install and configure cc-connect.

这一步的优点是省手工输入，缺点也很明显：Agent 可能会替你执行安装、写配置、选择权限。执行前最好先确认它准备改哪些文件，尤其是工作目录和权限模式。

方式 B：手动安装并打开 Web UI

npm install -g cc-connect
cc-connect

第一次运行后，项目会创建默认数据目录和配置文件，并输出本地 Web 管理地址。也可以运行：

cc-connect web

这里有个很容易误会的点：cc-connect web 主要是打开管理页面，不等于服务进程已经启动。配置完成后，仍然要在另一个终端运行 cc-connect。

3. 确认安装结果

安装向导完成后，至少检查三件事：

cc-connect --version
which cc-connect
claude --version   # 或 codex --version

在 Windows 上把 which 换成 where。如果 Agent 命令找不到，先修复 PATH，不要急着进入扫码环节。

四、接入飞书：推荐先走 setup

飞书接入是这篇教程的主线。当前 cc-connect 的飞书指南提供统一入口：

cc-connect feishu setup --project home

home 只是项目名，可以换成自己的名称。如果已有 App ID 和 App Secret，也可以按当前文档使用带凭证的 setup/bind 方式；如果没有凭证，向导会进入新建流程。

1. 创建或关联飞书应用

无论使用命令向导还是飞书开放平台后台，都要把下面几层关系分清：

飞书应用
  ├── 机器人能力
  ├── App ID / App Secret
  ├── 消息和用户相关权限
  ├── 事件订阅
  └── 发布状态与可用范围

项目文档提到，扫码新建流程可能会协助预配部分权限和事件订阅，但这不是“扫完码就不用检查后台”的理由。建议回到飞书开放平台，逐项确认应用已经启用机器人能力，并检查消息接收事件、发送消息权限和应用发布状态。

2. 检查事件订阅

常见的消息接收事件是：

im.message.receive_v1

如果使用交互卡片，还要按项目文档检查卡片回调配置。卡片按钮点击后没有反应，往往不是 Agent 挂了，而是事件订阅或应用版本没有重新发布。

3. 检查配置文件

手动配置时，结构可以参考下面这个最小示例。字段名称和平台选项以当前项目的 config.example.toml 为准：

[[projects]]
name = "home"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/your/project"
mode = "default"

[[projects.platforms]]
type = "feishu"

[projects.platforms.options]
app_id = "cli_xxxxxxxxx"
app_secret = "请使用环境变量或安全存储"

如果使用 Codex，把 Agent 类型改成项目当前文档支持的 codex 配置；不要把 Claude Code 的认证文件直接当成 Codex 的认证文件。

4. 启动服务并验证

cc-connect

验证不要只看 Web 页面。最少做一次完整回路：在飞书中给机器人发消息，观察本地终端是否收到事件，再看飞书是否收到回复。

日志中可以重点找这些信息：

platform started
cc-connect is running
connected to .../ws/...
message received
session spawned

不同版本的日志文字可能不同，但“平台启动—收到消息—启动会话—返回结果”这条链路应该完整出现。

五、接入 Codex：Agent 换了，桥接层不变

接入 Codex 的核心逻辑和 Claude Code 一样：先让 Codex CLI 在本地完成安装与登录，再把它绑定到一个 cc-connect 项目。

可以把它理解为：

飞书配置不变
平台机器人不变
只替换项目里的 Agent 类型和认证状态

需要注意三点。

第一，桌面端和 CLI 不是一回事。项目需要的是可被终端调用的 Codex CLI，只有桌面端并不能自动满足这个前置条件。

第二，Claude Code 和 Codex 的登录状态彼此独立。一个能回复，不代表另一个也能回复。

第三，不要一上来就打开最高权限模式。项目中常见的 default 模式会在需要时请求确认；某些自动批准或 bypass 权限模式虽然更顺手，但也意味着 Agent 可以直接执行更多操作。测试阶段先用默认模式，确认工作目录和指令边界后再决定是否放宽。

六、个人微信、企业微信和飞书不是一回事

这里是最容易被一句“接入微信”带偏的地方。

个人微信

cc-connect 当前文档把个人微信通道写作 Weixin / ilink，并提供类似下面的配置入口：

cc-connect weixin setup --project home

项目文档描述的是特定的个人微信 ilink 通道，它与企业微信 WeCom 不是同一套协议，也不等于微信网站应用 OAuth 登录，更不能泛化成“个人微信官方开放 API”。

如果确实使用这个通道，至少要检查 allow_from。空值或通配符会放宽发送者限制，适合临时调试，不适合直接当生产配置。

企业微信

企业微信有自己的应用和消息接口，应该按照企业微信的应用凭证、事件和权限体系配置。不要把个人微信的扫码流程复制到企业微信，也不要把企业微信的应用消息接口写成个人微信能力。

飞书

飞书则是另一套应用机器人和事件订阅体系。本文展示的 feishu setup 是 cc-connect 的项目引导命令，真正上线前仍然要回到飞书开放平台核对应用状态、权限和可用范围。

七、常见故障排查

1. claude 或 codex 找不到

先执行：

which claude   # Windows 使用 where claude
which codex

如果没有路径，修复安装目录和 PATH；如果有路径但 cc-connect 找不到，检查启动 cc-connect 时使用的 shell 环境是否加载了同一份配置。

2. 扫码成功，但平台收不到消息

按顺序检查：Agent CLI 是否能单独运行、cc-connect 是否仍在前台运行、平台应用是否已发布、消息事件是否订阅、发送消息权限是否生效，以及 allow_from 是否把自己拦住。

3. 飞书卡片按钮无响应

优先检查卡片回调事件和应用版本发布状态。如果暂时不需要交互卡片，可以按项目当前文档把卡片能力关闭，先回退到纯文本消息，排除问题范围。

4. 日志显示收到消息，但 Agent 没回复

这通常说明平台层已经通了，问题转移到了 Agent 层。检查 CLI 登录状态、工作目录是否存在、权限模式是否阻塞、模型或 API 是否可用。不要看到“消息已收到”就认定整个链路成功。

5. 个人微信能扫码，但不建议放开所有人

扫码只是身份绑定的一步，不是访问控制。先设置允许的发送者，再逐步测试私聊、群聊和文件能力。涉及代码、命令和本地文件时，默认权限应该尽量收紧。

八、我建议的最小可行配置

如果只是第一次试用，可以按这个顺序：

1. 本地单独验证 claude 或 codex
2. 安装 cc-connect
3. 只创建一个项目和一个工作目录
4. 先接飞书，不要同时开多个平台
5. 使用 default 权限模式
6. 发一条简单消息验证收发
7. 再逐步增加微信通道、文件能力和自动化

把所有平台一次性打开，看起来很“全”，实际最难排障。先让一条链路稳定跑通，再扩展，效率反而更高。

总结

cc-connect 的价值不在于把 Claude 或 Codex 变成一个普通聊天机器人，而在于把本地 Agent、工作目录和聊天入口连接起来。飞书接入的关键是应用、权限、事件订阅和长连接；Codex 接入的关键是先准备好 CLI 和独立登录状态；个人微信则必须区分项目通道和微信官方接口，不能用一句“微信也能接”掩盖协议差异。

如果你需要，可以把 llapi.org 作为一个中转入口参考。

你现在更想把 Agent 接到飞书，还是先把本地 CLI 的权限和工作目录整理好？

标签： Claude Code、Codex、cc-connect、飞书机器人、Lark、微信、CLI、AI 办公自动化