okooooooo/cc-connect

0 Fork 0

Files

T

Jerry d76639360c feat(core): rotate sessions after idle inactivity (#400 )

2026-04-02 09:26:35 +08:00

21 KiB

Raw Blame History

Usage Guide

Complete guide to using cc-connect features.

Session Management
Permission Modes
API Provider Management
Model Selection
Work Directory Switching (/dir, /cd)
Feishu Setup CLI
Weixin (personal) Setup CLI
Claude Code Router Integration
Voice Messages (STT)
Voice Reply (TTS)
Image and File Send-Back
Scheduled Tasks (Cron)
Multi-Bot Relay
Daemon Mode
Multi-Workspace Mode
Web Admin Dashboard (Beta)
Bridge — External Adapter Access (Beta)
Configuration Reference

Session Management

Each user gets an independent session with full conversation context. Manage sessions via slash commands:

Command	Description
`/new [name]`	Start a new session
`/list`	List all agent sessions for this project
`/switch <id>`	Switch to a different session
`/current`	Show current session info
`/history [n]`	Show last n messages (default 10)
`/usage`	Show account/model quota usage (if supported)
`/provider [...]`	Manage API providers
`/model [switch <alias>]`	List available models or switch by alias
`/dir [path]`	Show or switch the agent work directory
`/allow <tool>`	Pre-allow a tool (next session)
`/reasoning [level]`	View or switch reasoning effort (Codex)
`/mode [name]`	View or switch permission mode
`/quiet`	Toggle thinking/tool progress messages
`/stop`	Stop current execution
`/help`	Show available commands

During a session, the agent may request tool permissions. Reply allow / deny / allow all.

You can also configure automatic session rotation after inactivity:

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

When enabled, the next normal message after a long idle period starts in a fresh session automatically, without deleting the old session from /list.

Permission Modes

All agents support permission modes switchable at runtime via /mode.

Claude Code Modes

Mode	Config Value	Behavior
Default	`default`	Every tool call requires approval
Accept Edits	`acceptEdits` / `edit`	File edits auto-approved
Auto	`auto`	Claude decides when to ask for permission
Plan Mode	`plan`	Claude only plans, no execution
YOLO	`bypassPermissions` / `yolo`	All tools auto-approved

Codex Modes

Mode	Config Value	Behavior
Suggest	`suggest`	Only trusted commands run without approval
Auto Edit	`auto-edit`	Model decides when to ask
Full Auto	`full-auto`	Auto-approve with sandbox
YOLO	`yolo`	Bypass all approvals and sandbox

Cursor Agent Modes

Mode	Config Value	Behavior
Default	`default`	Trust workspace, ask before tools
Force (YOLO)	`force` / `yolo`	Auto-approve all
Plan	`plan`	Read-only analysis
Ask	`ask`	Q&A style, read-only

Gemini CLI Modes

Mode	Config Value	Behavior
Default	`default`	Prompt for approval
Auto Edit	`auto_edit` / `edit`	Auto-approve edits
YOLO	`yolo`	Auto-approve all
Plan	`plan`	Read-only plan mode

Qoder CLI / OpenCode / iFlow CLI

Mode	Config Value	Behavior
Default	`default`	Standard permissions
YOLO	`yolo`	Skip all checks

Configuration

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

Switch at runtime:

/mode          # show current and available modes
/mode yolo     # switch to YOLO mode
/mode default  # switch back

API Provider Management

Switch between API providers at runtime without restart.

Configure Providers

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

[[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-compatible, 1M context
[[projects.agent.providers]]
name = "minimax"
api_key = "your-minimax-api-key"
base_url = "https://api.minimax.io/v1"
model = "MiniMax-M2.7"

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

CLI Commands

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  # from cc-switch

Chat Commands

/provider                   Show current provider
/provider list              List all providers
/provider add <name> <key> [url] [model]
/provider remove <name>
/provider switch <name>
/provider <name>            Shortcut for switch

Env Var Mapping

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`	use `env` map
OpenCode	`ANTHROPIC_API_KEY`	use `env` map
iFlow CLI	`IFLOW_API_KEY`	`IFLOW_BASE_URL`

Model Selection

Pre-configure a list of selectable models per provider using [[providers.models]]. Each entry has a model identifier and an optional alias (short name shown in /model).

Configure Models

[[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"

Chat Commands

/model              List available models (format: alias - model)
/model switch <alias>      Switch to the model matching the alias
/model switch <name>       Switch to the model by its full name
/model <alias>             Legacy syntax, still supported

When models is configured, /model shows exactly that list without making an API round-trip. When omitted, models are fetched from the provider API or fall back to a built-in list.

Work Directory Switching (`/dir`, `/cd`)

Switch where the next agent session starts, directly from chat.

Chat Commands

/dir                    Show current work directory and recent history
/dir <path>             Switch to a path (relative or absolute)
/dir <number>           Switch to a directory from history
/dir -                  Switch back to previous directory
/dir help               Show command usage
/cd <path>              Backward-compatible alias of /dir <path>

Behavior Notes

Directory changes apply to the next session in the current project.
Relative paths are resolved from the current agent work directory.
Directory history is project-scoped and can be switched by index.
/cd is kept for compatibility, but /dir is the primary command.

Examples:

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

Feishu Setup CLI

Use CLI to create or bind Feishu/Lark bot credentials and write them back to config.toml.

# Recommended: unified entry
cc-connect feishu setup --project my-project
cc-connect feishu setup --project my-project --app cli_xxx:sec_xxx

# Force modes (usually unnecessary)
cc-connect feishu new --project my-project
cc-connect feishu bind --project my-project --app cli_xxx:sec_xxx

Differences:

setup: unified entry. No credentials => behaves like new; with --app => behaves like bind.
new: force QR onboarding flow; rejects --app.
bind: force credential binding flow; requires credentials.

Behavior:

setup uses QR onboarding by default, or bind mode when --app is provided.
If --project does not exist, it is created automatically.
If project exists but has no feishu/lark platform, one is added automatically.
The command writes credentials (app_id, app_secret); in QR onboarding flow, Feishu usually pre-configures permissions and event subscriptions.
Still verify app publish status and availability scope in Feishu Open Platform.
Runtime platform config also supports an optional domain override for Feishu/Lark API endpoints; this does not change setup/onboarding URLs.

Weixin (personal) Setup CLI

Weixin personal chat uses the ilink bot HTTP API (long polling + sendMessage, same family as OpenClaw openclaw-weixin). Use the CLI to scan a QR code or bind an existing Bearer token and write config.toml.

Full walkthrough (Chinese): docs/weixin.md.

cc-connect weixin setup --project my-project
cc-connect weixin bind --project my-project --token '<token>'
cc-connect weixin new --project my-project

Notes:

setup without --token runs QR login; with --token behaves like bind.
Auto-creates the project and/or a weixin platform block when missing.
After login, send a message from WeChat once so context_token is cached.
See cc-connect weixin help for flags (--api-url, --cdn-url, --route-tag, etc.).

Claude Code Router Integration

Claude Code Router routes requests to different model providers.

Setup

Install: npm install -g @musistudio/claude-code-router
Configure ~/.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"
  }
}

Start: ccr start
Configure cc-connect:

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

Voice Messages (Speech-to-Text)

Send voice messages — cc-connect transcribes them automatically.

Supported: Feishu, WeChat Work, Telegram, LINE, Discord, Slack

Requirements: OpenAI/Groq API key, ffmpeg

Configure

[speech]
enabled = true
provider = "openai"    # or "groq"
language = ""          # "zh", "en", or auto-detect

[speech.openai]
api_key = "sk-xxx"
# base_url = ""
# model = "whisper-1"

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

Install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

Voice Reply (Text-to-Speech)

Synthesize AI replies into voice messages.

Supported: Feishu (Lark)

Configure

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

[tts.qwen]
api_key = "sk-xxx"
# model = "qwen3-tts-flash"

TTS Modes

Mode	Behavior
`voice_only`	Reply with voice only when user sends voice
`always`	Always send voice reply

Switch: /tts always or /tts voice_only

Image and File Send-Back

When an agent generates a local image, PDF, report, bundle, or other file and needs to deliver it directly to the current chat, use attachment mode in cc-connect send.

Currently supported platforms:

Feishu
Telegram

When to run setup first

If the current agent does not natively inject the system prompt, run this once in chat after upgrading:

/bind setup

or:

/cron setup

These two commands write the same cc-connect instructions. Either one is enough. After that, the agent knows:

normal text replies should be returned normally
generated attachments should be sent back with cc-connect send --image/--file

If you have run setup before, run it again after upgrading so the instructions are refreshed to the latest version.

Config switch

Add this to config.toml if you want to disable agent-driven attachment send-back:

attachment_send = "off"

The default is on. This switch is independent from the agent's /mode and only affects cc-connect send --image/--file.

CLI examples

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

Notes:

--image is for image attachments.
--file is for any file attachment.
--message is optional and sends a text note before the attachments.
--image and --file can both be repeated.
Absolute paths are recommended so the command does not depend on the agent's current working directory.
With attachment_send = "off", image/file send-back is blocked but ordinary text replies still work.

Typical use cases

The agent generates a screenshot or chart and should send it directly to the user.
The agent generates a PDF, Markdown export, log bundle, or patch file that should be delivered as an attachment.
The agent wants to send a short status message together with one or more generated files.

Important notes

This command is for attachment delivery, not ordinary text replies.
The files must exist on the local machine where the agent runs.
There must be an active session; otherwise the command fails because cc-connect has no chat context to deliver to.
Platform-specific file size and file type limits still apply.

Scheduled Tasks (Cron)

Create scheduled tasks that run automatically.

Chat Commands

/cron                                          List all jobs
/cron add <min> <hour> <day> <mon> <wk> <prompt>   Create job
/cron del <id>                                 Delete job
/cron enable <id>                              Enable job
/cron disable <id>                             Disable job

Example:

/cron add 0 6 * * * Summarize GitHub trending repos

CLI Commands

cc-connect cron add --cron "0 6 * * *" --prompt "Summarize GitHub trending" --desc "Daily Trending"
cc-connect cron list
cc-connect cron del <job-id>

Optional: --session-mode new-per-run starts a fresh agent session on each run (default is reuse, same as before). --timeout-mins N sets how long the scheduler waits per run (0 = no limit; omit = 30 minutes).

Natural Language (Claude Code)

"Every day at 6am, summarize GitHub trending"

Claude Code auto-creates the cron job. For other agents that rely on memory files, run /cron setup or /bind setup once first; both write the same instructions.

Multi-Bot Relay

Cross-platform bot communication in group chats.

Group Chat Binding

/bind              Show bindings
/bind claudecode   Add claudecode project
/bind gemini       Add gemini project
/bind -claudecode  Remove claudecode

Bot-to-Bot Communication

cc-connect relay send --to gemini "What do you think about this architecture?"

Daemon Mode

Run as background service.

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

Multi-Workspace Mode

One bot serving multiple workspaces per channel.

Configure

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

[projects.agent]
type = "claudecode"

Commands

/workspace                    Show current binding
/workspace bind <name>        Bind local folder
/workspace init <git-url>     Clone and bind repo
/workspace unbind             Remove binding
/workspace list               List all bindings

How It Works

Channel name #project-a → auto-binds to base_dir/project-a/
Each channel has isolated sessions and agent state

Web Admin Dashboard (Beta)

Status: Beta. This feature is available since v1.2.2-beta.5. The UI and API may change in future releases.

A full-featured management UI embedded in the binary — project CRUD, session management, cron job editor, global settings, chat interface, and i18n support.

Quick Setup (Chat Command)

The easiest way to enable web admin:

/web setup

This automatically enables both the Management API and the Bridge in config.toml, generates tokens, and prints the access URL. You may need to run /restart for changes to take effect.

After setup, open the URL shown (default http://localhost:9820) and log in with the token.

Check Status

/web           # or /web status — show current web admin URL and status

Manual Configuration

Add the following to config.toml:

[management]
enabled = true
port = 9820                     # Management UI & API listen port
token = "your-secret-token"     # Login token; /web setup generates one automatically
cors_origins = ["*"]            # Allowed CORS origins; empty = no CORS headers

Then restart cc-connect.

Build Options

Web assets are compiled into the binary by default. To exclude them (saves ~1MB):

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

When built with no_web, the /web command will report that web admin is not available.

Management API

The Management API is served on the same port as the UI. Base URL: http://<host>:<port>/api/v1

All API requests require the Authorization: Bearer <token> header.

Key endpoints:

Method	Path	Description
`GET`	`/api/v1/status`	System status (version, uptime, platforms)
`POST`	`/api/v1/restart`	Restart cc-connect
`POST`	`/api/v1/reload`	Reload configuration
`GET`	`/api/v1/projects`	List projects
`GET`	`/api/v1/sessions?project=<name>`	List sessions for a project
`GET`	`/api/v1/cron`	List cron jobs
`GET`	`/api/v1/settings`	Get global settings
`PATCH`	`/api/v1/settings`	Update global settings

Full API reference: management-api.md

Bridge — External Adapter Access (Beta)

Status: Beta. This feature is available since v1.2.2-beta.5. The protocol may change in future releases.

The Bridge exposes a WebSocket + REST server so external adapters (custom UIs, bots, scripts) can interact with cc-connect sessions — send messages, receive events, manage sessions.

Enable via Chat

The /web setup command enables Bridge automatically alongside the Management API.

Manual Configuration

Add the following to config.toml:

[bridge]
enabled = true
port = 9810                     # Bridge listen port (separate from management)
token = "your-bridge-secret"    # Auth token for WebSocket and REST
path = "/bridge/ws"             # WebSocket endpoint path
cors_origins = ["*"]            # Allowed CORS origins; empty = no CORS

Then restart cc-connect.

Authentication

All Bridge connections require a token. Supported methods:

Query parameter: ?token=<bridge-token>
Header: Authorization: Bearer <bridge-token>
Header: X-Bridge-Token: <bridge-token>

WebSocket

Connect to:

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

The WebSocket supports bidirectional messaging — send user messages to the agent and receive agent events (text, tool calls, permission requests, etc.) in real time.

REST API

Served on the same port as the WebSocket.

Method	Path	Description
`GET`	`/bridge/sessions?session_key=...&project=...`	List sessions
`POST`	`/bridge/sessions`	Create a new session
`GET`	`/bridge/sessions/{id}?session_key=...&project=...`	Get session detail + history
`DELETE`	`/bridge/sessions/{id}?session_key=...&project=...`	Delete a session
`POST`	`/bridge/sessions/switch`	Switch active session

Full protocol reference: bridge-protocol.md

Port Summary

Service	Default Port	Config Block
Management (Web UI + API)	9820	`[management]`
Bridge (WebSocket + REST)	9810	`[bridge]`

Configuration Reference

See config.example.toml for full examples.

Project Structure

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

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

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

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

[projects.platforms.options]
# platform-specific options

21 KiB Raw Blame History

Usage Guide

Table of Contents

Session Management

Permission Modes

Claude Code Modes

Codex Modes

Cursor Agent Modes

Gemini CLI Modes

Qoder CLI / OpenCode / iFlow CLI

Configuration

API Provider Management

Configure Providers

CLI Commands

Chat Commands

Env Var Mapping

Model Selection

Configure Models

Chat Commands

Work Directory Switching (/dir, /cd)

Chat Commands

Behavior Notes

Feishu Setup CLI

Weixin (personal) Setup CLI

Claude Code Router Integration

Setup

Voice Messages (Speech-to-Text)

Configure

Install ffmpeg

Voice Reply (Text-to-Speech)

Configure

TTS Modes

Image and File Send-Back

When to run setup first

Config switch

CLI examples

Typical use cases

Important notes

Scheduled Tasks (Cron)

Chat Commands

CLI Commands

Natural Language (Claude Code)

Multi-Bot Relay

Group Chat Binding

Bot-to-Bot Communication

Daemon Mode

Multi-Workspace Mode

Configure

Commands

How It Works

Web Admin Dashboard (Beta)

Quick Setup (Chat Command)

Check Status

Manual Configuration

Build Options

Management API

Bridge — External Adapter Access (Beta)

Enable via Chat

Manual Configuration

Authentication

WebSocket

REST API

Port Summary

Configuration Reference

Project Structure

21 KiB

Raw Blame History

Work Directory Switching (`/dir`, `/cd`)