sutong/cc-connect

Fork 0

Files

T

sutong 0bc3f02670 初始化仓库

2026-06-02 23:14:41 +08:00

26 KiB

Raw Blame History

使用指南

cc-connect 完整功能使用指南。

会话管理
权限模式
API Provider 管理
模型选择
工作目录切换（/dir、/cd）
引用查看（/show）
飞书配置 CLI
微信个人号配置 CLI
Claude Code Router 集成
语音消息（语音转文字）
语音回复（文字转语音）
图片与文件回传
定时任务 (Cron)
多机器人中继
守护进程模式
多工作区模式
Web 管理后台（Beta）
Bridge — 外部适配器接入（Beta）
配置参考

会话管理

每个用户拥有独立的会话和完整的对话上下文。通过斜杠命令管理：

命令	说明
`/new [名称]`	创建新会话
`/list`	列出当前项目的会话
`/switch <id>`	切换到指定会话
`/current`	查看当前会话
`/history [n]`	查看最近 n 条消息
`/usage`	查看账号/模型限额使用情况
`/provider [...]`	管理 API Provider
`/model [switch <alias>]`	列出可用模型或按别名切换
`/dir [路径]`	查看或切换 Agent 工作目录
`/show <引用>`	按引用查看文件、目录或代码片段
`/allow <工具名>`	预授权工具
`/reasoning [等级]`	查看或切换推理强度（Codex）
`/mode [名称]`	查看或切换权限模式
`/stop`	停止当前执行
`/help`	显示可用命令

会话中 Agent 请求工具权限时，回复允许 / 拒绝 / 允许所有。

也可以为项目开启“空闲后自动切换新会话”：

[[projects]]
name = "demo"
reset_on_idle_mins = 60

开启后，如果用户长时间未发消息，下一条普通消息会自动进入一个新的会话；旧会话仍会保留在 /list 中，不会被删除。

切换模型时保留历史

/model 切换模型时保留当前会话——agent 会在新模型下继续对话（不额外消耗 token）。注意模型切换作用于共享的 agent 实例——如果多个平台使用同一个 project，模型变更会影响所有平台。

权限模式

所有 Agent 支持运行时切换权限模式，通过 /mode 命令。

Claude Code 模式

模式	配置值	行为
默认	`default`	每次工具调用需确认
接受编辑	`acceptEdits` / `edit`	文件编辑自动通过
自动模式	`auto`	由 Claude 自动判断何时需要确认
计划模式	`plan`	只规划不执行
YOLO	`bypassPermissions` / `yolo`	全部自动通过

Codex 模式

模式	配置值	行为
建议	`suggest`	仅受信命令自动执行
自动编辑	`auto-edit`	模型自行决定
全自动	`full-auto`	自动通过 + 沙箱保护
YOLO	`yolo`	跳过所有审批

Cursor Agent 模式

模式	配置值	行为
默认	`default`	工具调用前询问
强制执行	`force` / `yolo`	自动批准所有
规划模式	`plan`	只读分析
问答模式	`ask`	问答风格，只读

Gemini CLI 模式

模式	配置值	行为
默认	`default`	每次需确认
自动编辑	`auto_edit` / `edit`	编辑自动通过
全自动	`yolo`	自动批准所有
规划模式	`plan`	只读规划

Qoder CLI / OpenCode / iFlow CLI

模式	配置值	行为
默认	`default`	标准权限
YOLO	`yolo`	跳过所有检查

配置示例

[projects.agent.options]
mode = "default"
# allowed_tools = ["Read", "Grep", "Glob"]

运行时切换：

/mode          # 查看当前和可用模式
/mode yolo     # 切换到 YOLO 模式
/mode default  # 切回默认

API Provider 管理

运行时切换 API Provider，无需重启。

配置 Provider

[projects.agent.options]
work_dir = "/path/to/project"
provider = "anthropic"

[[projects.agent.providers]]
name = "anthropic"
api_key = "sk-ant-xxx"

[[projects.agent.providers]]
name = "relay"
api_key = "sk-xxx"
base_url = "https://api.relay-service.com"
model = "claude-sonnet-4-20250514"

[[projects.agent.providers.models]]
model = "claude-sonnet-4-20250514"
alias = "sonnet"

[[projects.agent.providers.models]]
model = "claude-opus-4-20250514"
alias = "opus"

[[projects.agent.providers.models]]
model = "claude-haiku-3-5-20241022"
alias = "haiku"

# MiniMax — 兼容 OpenAI 接口，1M 超长上下文
[[projects.agent.providers]]
name = "minimax"
api_key = "your-minimax-api-key"
base_url = "https://api.minimax.io/v1"
model = "MiniMax-M2.7"

# Bedrock、Vertex 等
[[projects.agent.providers]]
name = "bedrock"
env = { CLAUDE_CODE_USE_BEDROCK = "1", AWS_PROFILE = "bedrock" }

CLI 命令

cc-connect provider add --project my-backend --name relay --api-key sk-xxx --base-url https://api.relay.com
cc-connect provider list --project my-backend
cc-connect provider remove --project my-backend --name relay
cc-connect provider import --project my-backend  # 从 cc-switch 导入

聊天命令

/provider                   查看当前 Provider
/provider list              列出所有
/provider add <名称> <key> [url] [model]
/provider remove <名称>
/provider switch <名称>
/provider <名称>            切换快捷方式

环境变量映射

Agent	api_key →	base_url →
Claude Code	`ANTHROPIC_API_KEY`	`ANTHROPIC_BASE_URL`
Codex	`OPENAI_API_KEY`	`OPENAI_BASE_URL`
Gemini CLI	`GEMINI_API_KEY`	使用 `env` 字段
OpenCode	`ANTHROPIC_API_KEY`	使用 `env` 字段
iFlow CLI	`IFLOW_API_KEY`	`IFLOW_BASE_URL`

模型选择

通过 [[providers.models]] 为每个 Provider 预配置可选模型列表。每个条目包含 model（模型标识符）和可选的 alias（别名，显示在 /model 中）。

配置模型

[[projects.agent.providers]]
name = "openai"
api_key = "sk-xxx"

[[projects.agent.providers.models]]
model = "gpt-5.3-codex"
alias = "codex"

[[projects.agent.providers.models]]
model = "gpt-5.4"
alias = "gpt"

[[projects.agent.providers.models]]
model = "gpt-5.3-codex-spark"
alias = "spark"

聊天命令

/model              列出可用模型（格式：alias - model）
/model switch <alias>      按别名切换模型
/model switch <name>       按完整名称切换模型
/model <alias>             兼容旧写法，仍然可用

配置了 models 时，/model 直接显示该列表，不发起 API 请求。未配置时，自动从 Provider API 获取或使用内置备选列表。

工作目录切换（`/dir`、`/cd`）

可直接在聊天中切换 Agent 下一次会话的工作目录。

聊天命令

/dir                    查看当前工作目录和最近历史
/dir <路径>             切换到指定路径（相对或绝对）
/dir <序号>             按历史序号切换目录
/dir -                  返回上一个目录
/dir help               查看命令用法
/cd <路径>              `/dir <路径>` 的兼容别名

行为说明

目录切换会作用于当前项目的下一次会话。
相对路径基于当前 Agent 工作目录解析。
目录历史按项目隔离，可通过序号快速切换。
/cd 为兼容保留，建议优先使用 /dir。

示例：

/dir ../another-repo
/dir 2
/dir -

本地引用展示配置（`[projects.references]`）

可选启用对 Agent 输出中的本地文件 / 目录 / 代码位置引用进行标准化与重渲染，提升在 IM 平台中的可读性。

这是一个 opt-in 功能：

未配置 [projects.references] 时，现有行为保持不变
只有命中 normalize_agents 和 render_platforms 时，才会启用

字段说明

normalize_agents
- 控制哪些 Agent 输出参与这套引用处理
- 当前初始支持：codex、claudecode、all
render_platforms
- 控制在哪些平台发送前应用展示重写
- 当前初始支持：feishu、weixin、all
display_path
- 控制路径主体的显示层级
- 可选值：absolute、relative、basename、dirname_basename、smart
marker_style
- 控制前缀标记样式
- 可选值：none、ascii、emoji
enclosure_style
- 控制路径主体的包裹样式
- 可选值：none、bracket、angle、fullwidth、code

支持的引用输入

当前初始支持识别这些常见形式：

绝对路径
相对路径
文件 / 目录引用
path:line
path:line:col
path:start-end
path#L42
Markdown 本地文件链接
Claude 风格的反引号绝对路径引用

行为说明

只处理 Agent 输出：
- thinking
- final response
- stream preview
- progress / card 中的 Agent 文本
不处理：
- 系统消息
- /workspace、/dir、/status 等命令回复
- raw tool result
网页链接会保持原样，不会被本地引用重写逻辑污染

引用查看（`/show`）

可直接基于一个文件 / 目录 / 代码位置引用查看内容，而不必手写 /shell sed ...。

聊天命令

/show <路径>                  查看文件前 80 行
/show <路径:行号>             查看该行附近上下文
/show <路径:起止行>           查看指定 range
/show <目录路径/>             查看一级目录列表

支持的输入形式包括：

绝对路径
相对路径（相对当前 Agent 工作目录）
path:line
path:line:col
path:start-end
path#L42
Markdown 本地文件链接，如：
- [file.ts](/abs/path/file.ts#L42)

行为说明

文件，无位置：
- 默认显示文件前 80 行
path:line / path#L42：
- 默认显示该位置附近上下文
path:start-end：
- 默认显示该 range
目录：
- 默认显示一级目录内容

说明：

/show 只解析“纯引用文本”，不解析前端展示层包装后的 📄 ... / [FILE] ... 这类样式
/show 属于本地文件系统查看命令，与 /shell、/dir 类似，默认受 admin_from 权限控制
执行 Shell 命令支持 ! 快捷前缀：!ls -la 等同于 /shell ls -la，! --timeout 300 npm install 可指定超时时间

示例：

/show ui/recovery_contact_form.tsx
/show svc/recovery_session_reconciler.go:12
/show svc/recovery_session_reconciler_test.go:8-17
/show docs/spec.v1/

飞书配置 CLI

可以直接通过 CLI 完成飞书/Lark 机器人创建或关联，并自动写回 config.toml：

# 推荐：统一入口
cc-connect feishu setup --project my-project
cc-connect feishu setup --project my-project --app cli_xxx:sec_xxx

# 强制模式（一般不需要）
cc-connect feishu new --project my-project
cc-connect feishu bind --project my-project --app cli_xxx:sec_xxx

区别说明：

setup：统一入口。没传凭证时等价 new，传了 --app 时等价 bind。
new：强制二维码新建，不接受 --app。
bind：强制关联已有机器人，必须提供凭证。

行为说明（通用）：

setup 默认走二维码新建；传入 --app 时自动切换到关联已有机器人。
--project 不存在会自动创建。
项目存在但没有 feishu/lark 平台时会自动补一个平台配置。
命令会回填凭证（app_id / app_secret）；扫码新建场景下飞书通常会预配权限和事件订阅。
建议在飞书开放平台再核验一次发布状态与可用范围。
运行时平台配置还支持可选 domain 覆盖 Feishu/Lark API 域名；这不会改变 setup/new/bind 的引导地址。

微信个人号配置 CLI

个人微信走 ilink 机器人网关（HTTP 长轮询，与 OpenClaw openclaw-weixin 同类）。可直接用 CLI 扫码登录或绑定已有 Token，并写回 config.toml。

完整图文流程与配置项说明见：docs/weixin.md。

# 推荐：终端展示二维码 + URL，微信扫码确认后自动写配置
cc-connect weixin setup --project my-project

# 已有 Bearer Token（例如从 OpenClaw 导出）
cc-connect weixin bind --project my-project --token '<token>'
cc-connect weixin setup --project my-project --token '<token>'

# 强制只走扫码（不接受 --token）
cc-connect weixin new --project my-project

区别说明：

setup：未传 --token 时走扫码；传了 --token 时等同绑定并可选校验。
new：强制扫码。
bind：强制绑定，必须 --token。

行为说明：

--project 不存在时会自动创建项目；项目里没有 weixin 平台时会自动追加一块 [[projects.platforms]]。
扫码成功后会写入 token，以及网关返回的 base_url（若有）、ilink_bot_id → account_id 等。
默认 --set-allow-from-empty=true：若 allow_from 为空，会用扫码用户的 ilink ID 预填，便于收紧权限。
绑定时默认调用 getUpdates 校验 Token；可用 --skip-verify 跳过。
首次使用后请在微信里 先发一条消息，以便缓存 context_token，否则可能无法回复。

常用参数：--api-url、--cdn-url、--timeout、--qr-image、--route-tag、--bot-type、--debug（详见 cc-connect weixin help 或 weixin.md）。

Claude Code Router 集成

Claude Code Router 可将请求路由到不同模型提供商。

安装配置

安装：npm install -g @musistudio/claude-code-router
配置 ~/.claude-code-router/config.json：

{
  "APIKEY": "your-secret-key",
  "Providers": [
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-xxx",
      "models": ["deepseek-chat", "deepseek-reasoner"],
      "transformer": { "use": ["deepseek"] }
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",
    "think": "deepseek,deepseek-reasoner"
  }
}

启动：ccr start
配置 cc-connect：

[projects.agent.options]
router_url = "http://127.0.0.1:3456"
router_api_key = "your-secret-key"

语音消息（语音转文字）

发送语音消息，自动转文字。

支持平台： 飞书、企业微信、Telegram、LINE、Discord、Slack

前置条件： OpenAI/Groq API Key，ffmpeg

配置

[speech]
enabled = true
provider = "openai"    # 或 "groq"
language = ""          # "zh"、"en" 或留空自动检测

[speech.openai]
api_key = "sk-xxx"

# [speech.groq]
# api_key = "gsk_xxx"
# model = "whisper-large-v3-turbo"

安装 ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

语音回复（文字转语音）

将 AI 回复合成语音发送。

支持平台： 飞书

配置

[tts]
enabled = true
provider = "qwen"        # 或 "openai"
voice = "Cherry"
tts_mode = "voice_only"  # "voice_only" | "always"
max_text_len = 0

[tts.qwen]
api_key = "sk-xxx"

TTS 模式

模式	行为
`voice_only`	仅当用户发语音时才语音回复
`always`	始终语音回复

切换：/tts always 或 /tts voice_only

图片与文件回传

当 Agent 在本地生成了图片、PDF、日志包、报表等文件，需要把结果直接发回当前聊天时，可以使用 cc-connect send 的附件模式。

当前支持平台：

飞书
Telegram

什么时候需要先执行 setup

如果当前 Agent 不是“原生 system prompt 注入”类型，升级到包含该功能的版本后，建议先在聊天里执行一次：

/bind setup

或者：

/cron setup

这两个命令写入的是同一份 cc-connect 指令。执行任意一个即可。这样 Agent 才会知道：

普通文本回复直接正常输出
生成附件后用 cc-connect send --image/--file 回传

如果你以前已经执行过 setup，也建议升级后重新执行一次，以刷新到最新指令。

配置开关

如果你想禁用 agent 主动回传附件，可以在 config.toml 里加入：

attachment_send = "off"

默认值是 on。这个开关与 agent 的 /mode 独立，只影响 cc-connect send --image/--file 这条图片/文件回传路径。

CLI 用法

cc-connect send --image /absolute/path/to/chart.png
cc-connect send --file /absolute/path/to/report.pdf
cc-connect send --file /absolute/path/to/report.pdf --image /absolute/path/to/chart.png

说明：

--image 用于图片附件。
--file 用于任意文件附件。
--message 可选，用于先发一段说明文字，再发附件。
--image 和 --file 都可以重复多次。
建议使用绝对路径，避免 Agent 当前工作目录变化导致找不到文件。
如果设置了 attachment_send = "off"，图片/文件回传会被拒绝，但普通文本回复仍然正常。

典型场景

Agent 生成了截图或图表，需要直接发给用户。
Agent 生成了 PDF、Markdown 导出、日志包或补丁文件，需要作为附件交付。
Agent 想告诉用户“结果已生成”，同时附上一个或多个文件。

注意事项

这个命令是给“附件回传”用的，不要拿它代替普通文本回复。
只能发送本机上 Agent 可访问到的文件。
必须存在活跃会话；如果当前项目没有活动聊天上下文，命令会失败。
平台本身仍可能有文件大小或文件类型限制。

定时任务 (Cron)

创建自动执行的定时任务。

聊天命令

/cron                                          列出所有任务
/cron add <分> <时> <日> <月> <周> <任务描述>      创建任务
/cron del <id>                                 删除任务
/cron enable <id>                              启用
/cron disable <id>                             禁用

示例：

/cron add 0 6 * * * 帮我收集 GitHub trending 并总结

CLI 命令

cc-connect cron add --cron "0 6 * * *" --prompt "总结 GitHub trending" --desc "每日趋势"
cc-connect cron list
cc-connect cron edit <job-id> <field> <value>   # 可改 cron_expr / prompt / enabled / mute / timeout_mins 等
cc-connect cron del <job-id>

可选：--session-mode new-per-run 每次触发使用新的 agent 会话（默认 reuse 与旧行为一致）。--timeout-mins N 设置单次调度最长等待分钟数（0 表示不限制；省略为 30 分钟）。

自然语言（Claude Code）

"每天早上6点帮我总结 GitHub trending"

Claude Code 会自动创建定时任务。对依赖记忆文件的其他 Agent，先执行一次 /cron setup 或 /bind setup，效果相同。

多机器人中继

跨平台机器人通信，群聊多机器人协作。

群聊绑定

/bind              查看绑定
/bind claudecode   添加 claudecode 项目
/bind gemini       添加 gemini 项目
/bind -claudecode  移除 claudecode

机器人间通信

cc-connect relay send --to gemini "你觉得这个架构怎么样？"

守护进程模式

后台服务运行。

cc-connect daemon install --config ~/.cc-connect/config.toml
cc-connect daemon start
cc-connect daemon stop
cc-connect daemon restart
cc-connect daemon status
cc-connect daemon logs [-f]
cc-connect daemon uninstall

多工作区模式

一个 bot 服务多个工作区，每个频道一个独立工作目录。

配置

[[projects]]
name = "my-project"
mode = "multi-workspace"
base_dir = "~/workspaces"

[projects.agent]
type = "claudecode"

命令

/workspace                    查看当前绑定
/workspace bind <名称>        绑定本地文件夹
/workspace init <git-url>     克隆仓库并绑定
/workspace unbind             解除绑定
/workspace list               列出所有绑定

工作原理

频道名 #project-a → 自动绑定 base_dir/project-a/
每个频道有独立的会话和 Agent 状态

Web 管理后台（Beta）

状态：Beta。 此功能自 v1.2.2-beta.5 起可用，UI 和 API 在后续版本中可能调整。

内嵌在二进制中的全功能管理界面，支持项目管理、会话管理、定时任务编辑、全局设置、聊天界面、多语言等。

快速启用（聊天命令）

最简单的方式，在聊天中发送：

/web setup

该命令会自动在 config.toml 中启用 Management API 和 Bridge，生成 token，并返回访问地址。首次启用后需要执行 /restart 使配置生效。

启用后，打开返回的地址（默认 http://localhost:9820），用显示的 token 登录即可。

查看状态

/web           # 或 /web status — 查看 Web 管理后台的地址和启用状态

手动配置

在 config.toml 中添加：

[management]
enabled = true
port = 9820                     # 管理后台监听端口
token = "your-secret-token"     # 登录 token；/web setup 会自动生成
cors_origins = ["*"]            # 允许的 CORS 来源；留空则不设置 CORS 头

然后重启 cc-connect。

构建选项

Web 前端资源默认编译进二进制。如果想排除（减小约 1MB）：

make build-noweb
# 或
go build -tags 'no_web' ./cmd/cc-connect

使用 no_web 构建时，/web 命令会提示 Web 管理后台不可用。

Management API

API 与 Web UI 共用同一端口。基础 URL：http://<host>:<port>/api/v1

所有 API 请求需要 Authorization: Bearer <token> 请求头。

主要接口：

方法	路径	说明
`GET`	`/api/v1/status`	系统状态（版本、运行时间、已连接平台）
`POST`	`/api/v1/restart`	重启 cc-connect
`POST`	`/api/v1/reload`	重新加载配置
`GET`	`/api/v1/projects`	项目列表
`GET`	`/api/v1/sessions?project=<name>`	查询项目的会话列表
`GET`	`/api/v1/cron`	定时任务列表
`GET`	`/api/v1/settings`	获取全局设置
`PATCH`	`/api/v1/settings`	更新全局设置

完整 API 参考：management-api.md（中文版）

Bridge — 外部适配器接入（Beta）

状态：Beta。 此功能自 v1.2.2-beta.5 起可用，协议在后续版本中可能调整。

Bridge 提供 WebSocket + REST 服务，让外部适配器（自定义 UI、机器人、脚本等）可以接入 cc-connect —— 发送消息、接收 Agent 事件、管理会话。

通过聊天启用

/web setup 命令会同时启用 Bridge 和管理后台，无需额外操作。

手动配置

在 config.toml 中添加：

[bridge]
enabled = true
port = 9810                     # Bridge 监听端口（与管理后台分开）
token = "your-bridge-secret"    # WebSocket 和 REST 的认证 token
path = "/bridge/ws"             # WebSocket 端点路径
cors_origins = ["*"]            # 允许的 CORS 来源；留空则不设置 CORS

然后重启 cc-connect。

认证方式

所有 Bridge 连接需要 token 认证，支持三种方式：

URL 参数：?token=<bridge-token>
请求头：Authorization: Bearer <bridge-token>
请求头：X-Bridge-Token: <bridge-token>

WebSocket 接入

连接地址：

ws://<host>:<bridge-port>/bridge/ws?token=<bridge-token>

WebSocket 支持双向通信 —— 向 Agent 发送消息，并实时接收 Agent 的文本回复、工具调用、权限请求等事件。

REST API

与 WebSocket 共用同一端口。

方法	路径	说明
`GET`	`/bridge/sessions?session_key=...&project=...`	查询会话列表
`POST`	`/bridge/sessions`	创建新会话
`GET`	`/bridge/sessions/{id}?session_key=...&project=...`	获取会话详情及历史
`DELETE`	`/bridge/sessions/{id}?session_key=...&project=...`	删除会话
`POST`	`/bridge/sessions/switch`	切换当前活跃会话

完整协议参考：bridge-protocol.md（中文版）

端口汇总

服务	默认端口	配置块
管理后台（Web UI + API）	9820	`[management]`
Bridge（WebSocket + REST）	9810	`[bridge]`

配置参考

完整配置示例见 config.example.toml。

项目结构

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"  # 或 codex, cursor, gemini, qoder, opencode, iflow

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

[[projects.platforms]]
type = "feishu"  # 或 wps-xiezuo, dingtalk, telegram, slack, discord, wecom, weixin, line, qq, qqbot

[projects.platforms.options]
# 平台特定配置

26 KiB Raw Blame History Unescape Escape

使用指南

目录

会话管理

切换模型时保留历史

权限模式

Claude Code 模式

Codex 模式

Cursor Agent 模式

Gemini CLI 模式

Qoder CLI / OpenCode / iFlow CLI

配置示例

API Provider 管理

配置 Provider

CLI 命令

聊天命令

环境变量映射

模型选择

配置模型

聊天命令

工作目录切换（/dir、/cd）

聊天命令

行为说明

本地引用展示配置（[projects.references]）

推荐配置

字段说明

支持的引用输入

行为说明

推荐默认值说明

引用查看（/show）

聊天命令

行为说明

飞书配置 CLI

微信个人号配置 CLI

Claude Code Router 集成

安装配置

语音消息（语音转文字）

配置

安装 ffmpeg

语音回复（文字转语音）

配置

TTS 模式

图片与文件回传

什么时候需要先执行 setup

配置开关

CLI 用法

典型场景

注意事项

定时任务 (Cron)

聊天命令

CLI 命令

自然语言（Claude Code）

多机器人中继

群聊绑定

机器人间通信

守护进程模式

多工作区模式

配置

命令

工作原理

Web 管理后台（Beta）

快速启用（聊天命令）

查看状态

手动配置

构建选项

Management API

Bridge — 外部适配器接入（Beta）

通过聊天启用

手动配置

认证方式

WebSocket 接入

REST API

端口汇总

配置参考

项目结构

26 KiB

Raw Blame History

工作目录切换（`/dir`、`/cd`）

本地引用展示配置（`[projects.references]`）

引用查看（`/show`）