配置参考#

Unified ICC 完全通过环境变量配置（支持 .env 文件）。核心库中无需任何平台令牌或 API 密钥。

配置加载顺序#

配置按以下顺序加载（后者覆盖前者）：

默认值
~/.unified-icc/.env 文件
./.env 文件（当前工作目录）
环境变量

环境变量#

核心设置#

变量	默认值	说明
`UNIFIED_ICC_DIR`	`~/.unified-icc`	配置目录
`CCLARK_PROVIDER`	`claude`	默认 AI 助手 Provider

Tmux 设置#

变量	默认值	说明
`TMUX_SESSION_NAME`	`cclark`	tmux 会话名称
`TMUX_EXTERNAL_PATTERNS`	（空）	外部窗口发现模式

监控设置#

变量	默认值	说明
`MONITOR_POLL_INTERVAL`	`1.0`	轮询间隔（秒，最小 0.5）
`CCLARK_STATUS_POLL_INTERVAL`	`1.0`	状态轮询间隔（秒）

助手设置#

变量	默认值	说明
`CLAUDE_CONFIG_DIR`	`~/.claude`	Claude 配置目录
`AUTOCLOSE_DONE_MINUTES`	`30`	完成后自动关闭（分钟）
`AUTOCLOSE_DEAD_MINUTES`	`10`	死亡会话自动关闭（分钟）

Provider 命令覆盖#

覆盖各 Provider 的启动命令：

变量	格式
`CCLARK_CLAUDE_COMMAND`	覆盖 `claude` 命令
`CCLARK_CODEX_COMMAND`	覆盖 `codex` 命令
`CCLARK_GEMINI_COMMAND`	覆盖 `gemini` 命令
`CCLARK_PI_COMMAND`	覆盖 `pi` 命令
`CCLARK_SHELL_COMMAND`	覆盖 `shell` 命令

示例 .env 文件#

# 核心设置
UNIFIED_ICC_DIR=~/.unified-icc
CCLARK_PROVIDER=claude

# Tmux
TMUX_SESSION_NAME=cclark

# 监控
MONITOR_POLL_INTERVAL=1.0

# Provider 覆盖
CCLARK_CLAUDE_COMMAND=/usr/local/bin/claude

GatewayConfig 类#

from unified_icc import GatewayConfig, config

# 访问全局配置
print(config.tmux_session_name)  # "cclark"
print(config.provider_name)     # "claude"

# 或创建自定义配置
custom_config = GatewayConfig()
custom_config.tmux_session_name = "my-session"

GatewayConfig 属性#

属性	类型	说明
`config_dir`	`Path`	配置目录
`tmux_session_name`	`str`	tmux 会话名称
`tmux_main_window_name`	`str`	主窗口名称
`own_window_id`	`str \| None`	本网关所在窗口 ID
`tmux_external_patterns`	`str`	外部窗口发现模式
`state_file`	`Path`	主状态文件路径
`session_map_file`	`Path`	会话映射文件路径
`monitor_state_file`	`Path`	监控状态文件路径
`events_file`	`Path`	钩子事件文件路径
`mailbox_dir`	`Path`	邮箱目录路径
`claude_config_dir`	`Path`	Claude 配置目录
`claude_projects_path`	`Path`	Claude 项目路径
`monitor_poll_interval`	`float`	轮询间隔
`status_poll_interval`	`float`	状态轮询间隔
`provider_name`	`str`	默认 Provider
`autoclose_done_minutes`	`int`	完成状态自动关闭延迟
`autoclose_dead_minutes`	`int`	死亡状态自动关闭延迟

状态文件#

所有状态文件存储在 ~/.unified-icc/：

文件	说明
`state.json`	网关状态（频道、窗口、显示名称）
`session_map.json`	tmux 窗口 ↔ AI 助手会话映射
`monitor_state.json`	轮询偏移量和追踪中的会话
`events.jsonl`	钩子事件日志（追加写入）

状态文件格式：state.json#

{
    "channel_bindings": {
        "feishu:chat123:thread456": "@1"
    },
    "channel_meta": {
        "feishu:chat123:thread456": {
            "user_id": "U123456"
        }
    },
    "display_names": {
        "@1": "Claude Code"
    }
}

状态文件格式：session_map.json#

{
    "cclark:@1": {
        "session_id": "abc123",
        "transcript_path": "/home/user/.claude/projects/myproj/.claude/history/session_abc123.jsonl",
        "cwd": "/home/user/projects/myproj",
        "window_name": "claude",
        "provider_name": "claude"
    }
}

自定义配置示例#

from unified_icc import UnifiedICC, GatewayConfig
import os

# 方式 1：环境变量
os.environ["TMUX_SESSION_NAME"] = "my-session"
os.environ["MONITOR_POLL_INTERVAL"] = "0.5"
gateway = UnifiedICC()

# 方式 2：自定义配置对象
config = GatewayConfig()
config.tmux_session_name = "my-session"
config.monitor_poll_interval = 0.5
config.state_file = Path("/tmp/my-state.json")
gateway = UnifiedICC(gateway_config=config)

tmux 要求#

Unified ICC 要求：

tmux 2.6 或更高版本
能够创建新会话/窗口
可访问 tmux 命令

tmux Socket#

默认 unified-icc 使用默认 tmux socket。使用自定义 socket：

export TMUX_SOCKET_PATH=/tmp/my-tmux-socket

窗口命名#

窗口自动命名。自定义显示名称：

# 在前端中设置显示名称
from unified_icc import channel_router
channel_router.set_display_name(window_id, "我的项目")

Provider 特定配置#

Claude#

Claude Code 如果 claude 在 PATH 中则自动检测。指定特定版本：

export CCLARK_CLAUDE_COMMAND=/path/to/claude

Codex#

export CCLARK_CODEX_COMMAND=/path/to/codex

Gemini#

export CCLARK_GEMINI_COMMAND=/path/to/gemini

配置参考

Contents