故障排查#

启动失败#

“FEISHU_APP_ID environment variable is required”#

当 ~/.unified-icc/config.yaml 不存在时，配置单例会回退读取环境变量；此时缺少必需环境变量会抛出 ValueError。

推荐修复：创建 ~/.unified-icc/config.yaml：

apps:
  - name: "default"
    app_id: "cli_xxxxxxxxxxxxxxxx"
    app_secret: "xxxxxxxxxxxxxxxxxxxxxxxx"
    allowed_users: "all"
    provider: "claude"
    tmux_session: "cclark"
    health_port: 8080

“Cannot find unified-icc”#

pyproject.toml 中的依赖路径指向本地源码树。请先在 cclark/ 目录下运行 uv sync。

“Address already in use” 启动 health endpoint 时#

端口 8080（或配置中的 health_port）已被占用。

修复：设置不同端口：

# 在 ~/.unified-icc/config.yaml 中设置 health_port: 8081
cclark

飞书 WebSocket 事件#

飞书未收到事件#

确认飞书应用启用了事件订阅并允许通过长连接接收 im.message.receive_v1。
确认 cclark 进程正在运行，且日志显示 WebSocket 已连接。

检查 /health 是否在本机可访问：

curl http://127.0.0.1:8080/health
# 应返回：{"status": "ok"}

消息未被处理#

机器人自身消息：是否设置了 config.bot_user_id？机器人会跳过自身消息。
非文本消息：目前仅处理 msg_type=text。图片、文件等会被确认但不会处理。
用户不在白名单：config.is_user_allowed(user_id) 返回 False → 静默跳过。

目录浏览器 / 会话创建#

没有会话时普通消息只返回帮助#

这是预期行为。发送 #new 进入目录 / provider / mode 向导；不要依赖首条普通消息自动创建会话。

`#mkdir <name>` 失败#

#mkdir 只允许在 #new 的目录选择阶段创建当前目录下的单个子目录。绝对路径或 nested/path 这类嵌套路径会被拒绝；删除目录不由 cclark 提供。

确认目录后会话创建挂起#

会话创建流程依赖：

gateway.create_window() → tmux new-window 必须成功
gateway.bind_channel() → 频道-窗口映射已保存
gateway.send_to_window() → 文本已管道输入 tmux 窗格

请检查：

tmux 是否运行中（tmux list-sessions）
工作目录是否存在且可访问
提供方命令（claude、codex 等）是否已安装且在 PATH 中

权限提示卡片按钮无响应#

当前 Claude permission prompt 的飞书卡片按钮回调尚未接入。看到 Claude needs input 卡片时，直接回复卡片中列出的编号；选项数量不固定， cclark 会读取 Claude 当前终端 prompt 中的全部可见编号。

流式卡片不更新#

VerboseCardStreamer 需要已注册的 on_message 回调。如果 main._register_callbacks 静默失败，流式功能不会启动。

检查：/health 是否有响应？网关轮询循环是否在运行？可用 #new 命令验证——首条智能体输出后 3 秒内应出现流式卡片。

VerboseCardStreamer 创建重复卡片#

如果同一回合出现多个流式卡片，可能是 _state 注册表在两次刷新之间被清除了。确保 reset() 仅在取消绑定或会话结束时调用，不在同一会话的回合之间调用。

卡片过大（飞书错误）#

飞书强制每张卡片最大约 30 KB。请减少 cards/streaming.py 中的 _MAX_CHARS_PER_FLUSH 或在对智能体转录本推送到流式器前截断长输出。————-

“Session ‘default’ not found”#

unified-icc 网关要求 tmux 已安装且默认会话存在（或自动创建）。先启动 tmux：

tmux new -d -s default
# 或设置 CCLARK_TMUX_SESSION 为其他会话名

智能体相关#

“claude command not found”#

安装 Claude Code CLI：

npm install -g @anthropic-ai/claude-code
# 或：pip install claude-code

“codex command not found”#

安装 OpenAI Codex CLI：

npm install -g @openai/codex
# 或：pip install codex

文件上传失败#

飞书文件上传需要在应用权限中申请 im:file 作用域。检查：飞书开放平台 → 权限管理 → im:file。

故障排查

Contents