cc-ding

将 Claude Code 接入钉钉，构建企业级 AI 协作工作流。

Connect Claude Code to DingTalk for enterprise-grade AI collaboration.

中文 | English

中文 | 简体中文

将 Claude Code 接入钉钉，实现双向通信。支持多轮对话、任务队列、定时任务、图片识别，帮助团队以最低成本构建可私有化部署的 AI 助手。

交流群

扫码加入钉钉或微信交流群：

快速开始

安装

npm i cc-ding -g

初始化

cc-ding init -ci {clientId} -cs {clientSecret} -u {手机号或工号} -dt {defaultDingToken}

参数	说明
`-ci, --clientId`	钉钉应用 ClientId
`-cs, --clientSecret`	钉钉 Stream 连接密钥
`-u, --user`	管理员手机号或工号（自动设为 owner 并加入白名单）
`-dt, --defaultDingToken`	兜底钉钉机器人 Token（必填）
`-cn, --clientName`	机器人名称（可选，默认 "cc助手"）

编辑配置

配置文件位于 ~/.cc-ding/{clientId}/config.json，参考下方配置文件示例。

启动

# 直接启动
cc-ding run -ci {clientId}

# 推荐：PM2 守护进程
pm2 start --name "cc-ding-{clientId}" npx -- -p cc-ding cc-ding run -ci {clientId}

命令参考

会话

命令	说明
`/help`	查看所有命令
`/log [行数]`	查看会话日志
`/new [消息]`	开始新对话
`/resume [ID]`	恢复历史会话（不指定则恢复最近一个）
`/end`	结束当前会话

会话自动持久化到 active.json，重启后无缝恢复。群内所有白名单用户均可参与。

任务

/task <描述>       # 提交任务（自动排队顺序执行）
/task cancel       # 取消任务

定时任务

/cron <自然语言>             # Claude 自动生成 cron 表达式
/cron 0 9 * * * <描述>       # 直接指定 cron
/cron list                   # 查看列表
/cron pause <id> | resume <id>   # 暂停 / 恢复
/cron delete <id>            # 删除

文件操作

命令	说明
`/ls [目录] [层数]`	查看目录结构
`/bash <命令>`	执行任意命令（仅 owner/管理员，执行记录审计日志 `bash-audit.log`）

管理命令（仅 owner）

命令	说明
`/info [robot\|session\|task]`	查看配置/会话/任务信息
`/version`	版本信息
`/open [shell]`	打开工作目录
`/clean [all]`	清除历史和缓存
`/reset-apikeycfg`	重置 API Key 配置
`/cfg`	注册当前群到配置（支持 `--permissionMode` 设置权限模式）
`/auth [add\|del <用户>]`	管理群级白名单
`/destroy`	注销当前群机器人，删除工作目录和配置
`/freedom`	自由模式：开启后所有群成员均可使用机器人（跳过白名单限制，60s 内回复"确认"即可开启）
`/recorder [on\|exit]`	Recorder 模式：记录所有消息到本地（仅 owner 单聊）
`/reboot [--update]`	重启 cc-ding 应用

Web Console

cc-ding 提供了一个 Web 管理界面，用于可视化管理客户端配置、API Key、辅助文件等。

启动 Console

cc-ding console [--port 8080] [--host 0.0.0.0] [--open]

参数	说明
`--port`	HTTP 监听端口（默认 8080）
`--host`	HTTP 监听地址（默认 0.0.0.0）
`--open` / `--browser`	启动后自动打开浏览器
`--no-browser`	禁止自动打开浏览器

端口约定

服务	默认端口	环境变量	说明
Console	8080	-	Web 管理界面
A2A Hub	3002	`A2A_HUB_PORT`	Agent-to-Agent 协调服务

也可以通过聊天命令 /open console 在本地自动打开 Console 页面。

功能

客户端管理 — 查看所有客户端的在线状态、会话数、API Key 数量
配置编辑 — 查看脱敏后的配置、通过 dot-path 语法修改嵌套值、原始 JSON 编辑（写前自动备份）
API Key 管理 — 列表 / 添加 / 编辑 / 删除 / 重置，支持切换有效状态
文件管理 — 读写辅助 JSON 文件（menu.json、model.json、cron.json、todo.json、user-map.json、active.json）
环境变量查看 — 扫描配置中的 $ENV: 引用，显示当前进程环境变量值
全局配置 — 修改 Console 端口 / 监听地址、编辑 settings-tpl.json 模板
系统状态 — 版本、平台、运行时间、在线客户端数
热重载 — 向客户端进程发送 SIGUSR2 信号触发配置重载

URL 深度链接

/open console 命令会自动构建深度链接，例如：

http://localhost:8080?client=dingiexxdy25itrcuwtb&tab=config

client — 自动跳转到指定客户端详情页
tab — 自动切换到指定标签页（config / keys / files / env / raw）

配置说明

配置文件示例

{
  "clientName": "cc助手",
  "owner": "你的手机号",
  "whiteUserList": ["你的手机号"],
  "clientSecret": "钉钉Stream连接密钥",
  "defaultDingToken": "兜底钉钉机器人Token",
  "conversations": [
    {
      "conversationId": "群ID",
      "conversationTitle": "群名称",
      "dingToken": "群机器人Token",
      "whiteUserList": ["工号1", "工号2"],
      "agent": "指定agent（可选）",
      "useLocalOcr": true,
      "permissionMode": "bypassPermissions",
      "taskCfg": { "skill": "指定技能（可选）" },
      "freedomMode": false
    }
  ],
  "taskQueueSize": 50,
  "taskHandlerCount": 1,
  "sessionMaxConcurrency": 20,
  "includeThinking": false,
  "resultOnly": true,
  "debug": false
}

配置项速查

配置	说明
`whiteUserList`	全局白名单（手机号、工号或 userId）
`conversations[].whiteUserList`	群级白名单，优先级高于全局（手机号、工号或 userId）
`apiKeyCfg`	API Key 池化：429 自动切换、每日 0 点重置
`useLocalOcr`	图片本地 OCR（默认 `true`），模型支持图片时可设 `false`
`linkConversationId`	关联群 ID，多群共享同一 Claude 会话上下文
`permissionMode`	Claude 进程权限模式（默认 `acceptEdits`；`bypassPermissions` 需显式配置，启动时会告警），可选: `default`、`acceptEdits`、`plan`、`auto`、`bypassPermissions`、`dontAsk`
`freedomMode`	自由模式开关（默认 `false`，开启后跳过群用户白名单限制）
`preBash`	全局 `/bash` 前置命令
`agent`	AI 执行引擎：`claude`（默认）或 `codex`（OpenAI Codex CLI）

多 Agent 架构（v1.1.0）

cc-ding 引入了多 Agent 抽象层，支持在不同 AI 执行引擎之间切换。通过在群配置中设置 agent 字段，可以为不同群指定不同的执行引擎：

{
  "conversationId": "群ID",
  "agent": "claude"  // 或 "codex"
}

claude（默认）：使用 Claude Code CLI，支持 --resume 会话恢复、API Key 轮换、上下文压缩等完整功能
codex：使用 OpenAI Codex CLI，支持线程恢复（thread_id）、沙箱模式（full-auto）、自动超时恢复等

所有命令（/goon、/!、/new、/cc 等）均支持多 Agent 路由，无需额外配置。

安全说明

敏感字段（clientSecret、dingToken、defaultDingToken、apiKeyCfg[].apiKey）支持 $ENV:VAR_NAME 形式引用环境变量，避免明文落盘，例如 "clientSecret": "$ENV:DING_SECRET"
config.json 与 settings-ding.json 写入时自动收紧为 600 权限
/bash 仅限 owner/管理员执行，所有命令记录到 ~/.cc-ding/{clientId}/bash-audit.log

数据存储

所有数据存储在 ~/.cc-ding/{clientId}/ 目录下：

类型	路径
会话	`{MD5}/.sessions/{claudeSessionId
任务	`{MD5}/.tasks/{时间戳}/task.{json,log}`
定时任务	`cron.json`
图片缓存	`{MD5}/.images/`
用户映射	`user-map.json`

开发

pnpm install
pnpm run lint
pnpm run test
pnpm run build

English

Connect Claude Code to DingTalk for bidirectional communication. Supports multi-turn conversations, task queues, scheduled jobs, and image recognition — helping teams build privately deployable AI assistants at minimal cost.

Community

Scan the QR code to join our DingTalk or WeChat group:

Quick Start

Install

npm i cc-ding -g

Initialize

cc-ding init -ci {clientId} -cs {clientSecret} -u {phone_or_emp_id} -dt {defaultDingToken}

Parameter	Description
`-ci, --clientId`	DingTalk app ClientId
`-cs, --clientSecret`	DingTalk Stream connection secret
`-u, --user`	Admin phone number or employee ID (set as owner and added to whitelist)
`-dt, --defaultDingToken`	Fallback DingTalk bot Token (required)
`-cn, --clientName`	Bot name (optional, default "cc助手")

Edit Config

Config file is at ~/.cc-ding/{clientId}/config.json. See config example below.

Start

# Direct start
cc-ding run -ci {clientId}

# Recommended: PM2 daemon
pm2 start --name "cc-ding-{clientId}" npx -- -p cc-ding cc-ding run -ci {clientId}

Commands

Session

Command	Description
`/help`	View all commands
`/log [lines]`	View session logs
`/new [msg]`	Start a new conversation
`/resume [ID]`	Resume a previous session (latest if omitted)
`/end`	End the current session

Sessions are auto-persisted to active.json and restored on restart. All whitelisted users in the group can participate.

Task

/task <description>     # Submit task (auto-queued, sequential execution)
/task cancel            # Cancel a task

Scheduled

/cron <natural language>        # Claude auto-generates cron expression
/cron 0 9 * * * <description>   # Specify cron directly
/cron list                      # View all
/cron pause <id> | resume <id>  # Pause / resume
/cron delete <id>               # Delete

File Operations

Command	Description
`/ls [dir] [depth]`	View directory structure
`/bash <cmd>`	Execute arbitrary commands (owner/admin only, audited in `bash-audit.log`)

Admin (owner only)

Command	Description
`/info [robot\|session\|task]`	View config/session/task info
`/version`	Version info
`/open [shell]`	Open working directory
`/clean [all]`	Clear history and cache
`/reset-apikeycfg`	Reset API Key configuration
`/cfg`	Register current group to config (supports `--permissionMode` to set permission mode)
`/auth [add\|del <user>]`	Manage group whitelist
`/destroy`	Unregister group bot, delete working directory and config
`/freedom`	Freedom mode: all group members can use the bot (skip whitelist, reply "confirm" within 60s to activate)
`/recorder [on\|exit]`	Recorder mode: log all messages locally (owner single-chat only)
`/reboot [--update]`	Restart cc-ding application

Web Console

cc-ding provides a web administration interface for visual management of client configs, API keys, auxiliary files, and more.

Start Console

cc-ding console [--port 8080] [--host 0.0.0.0] [--open]

Parameter	Description
`--port`	HTTP listen port (default 8080)
`--host`	HTTP listen address (default 0.0.0.0)
`--open` / `--browser`	Auto-open browser on start
`--no-browser`	Disable auto-opening browser

Port Conventions

Service	Default Port	Env Variable	Description
Console	8080	-	Web management interface
A2A Hub	3002	`A2A_HUB_PORT`	Agent-to-Agent coordination service

You can also use the chat command /open console to open the Console page locally.

Login

Default credentials: admin / admin
Password change is required on first login
Bearer Token authentication, 24-hour expiry

Features

Client Management — View online status, conversation counts, API Key counts for all clients
Config Editing — View masked configs, patch nested values via dot-path syntax, raw JSON editing (auto-backup before write)
API Key Management — List / add / edit / delete / reset, toggle validity
File Management — Read/write auxiliary JSON files (menu.json, model.json, cron.json, todo.json, user-map.json, active.json)
Environment Variables — Scan config for $ENV: references and display current process.env values
Global Config — Change Console port / host, edit settings-tpl.json template
System Status — Version, platform, uptime, online client count
Hot Reload — Send SIGUSR2 signal to client processes to trigger config reload

URL Deep Links

The /open console command auto-builds deep links like:

http://localhost:8080?client=dingiexxdy25itrcuwtb&tab=config

client — Auto-navigate to the specified client detail page
tab — Auto-switch to the specified tab (config / keys / files / env / raw)

Configuration

Configuration Example

{
  "clientName": "cc助手",
  "owner": "your_phone_number",
  "whiteUserList": ["your_phone_number"],
  "clientSecret": "dingtalk_stream_secret",
  "defaultDingToken": "fallback_dingtalk_bot_token",
  "conversations": [
    {
      "conversationId": "group_id",
      "conversationTitle": "group_name",
      "dingToken": "group_bot_token",
      "whiteUserList": ["emp_id_1", "emp_id_2"],
      "agent": "specified_agent (optional)",
      "useLocalOcr": true,
      "permissionMode": "bypassPermissions",
      "taskCfg": { "skill": "specified_skill (optional)" },
      "freedomMode": false
    }
  ],
  "taskQueueSize": 50,
  "taskHandlerCount": 1,
  "sessionMaxConcurrency": 20,
  "includeThinking": false,
  "resultOnly": true,
  "debug": false
}

Config Quick Reference

Config	Description
`whiteUserList`	Global whitelist (phone, employee ID, or userId)
`conversations[].whiteUserList`	Group-level whitelist, higher priority than global (phone, employee ID, or userId)
`apiKeyCfg`	API Key pooling: auto-switch on 429, daily reset at midnight
`useLocalOcr`	Local image OCR (default `true`); set `false` if model supports images natively
`linkConversationId`	Link groups to share one Claude session context
`permissionMode`	Claude process permission mode (default `acceptEdits`; `bypassPermissions` must be set explicitly and warns at startup), options: `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`, `dontAsk`
`freedomMode`	Freedom mode toggle (default `false`; when enabled, skips group whitelist check)
`preBash`	Global pre-bash command for `/bash`
`agent`	AI execution engine: `claude` (default) or `codex` (OpenAI Codex CLI)

Multi-Agent Architecture (v1.1.0)

cc-ding introduces a multi-Agent abstraction layer, allowing different AI execution engines to be switched per group. Set the agent field in group config to choose the engine:

{
  "conversationId": "group_id",
  "agent": "claude"  // or "codex"
}

claude (default): Uses Claude Code CLI, supports --resume session recovery, API Key rotation, context compaction, and full feature set
codex: Uses OpenAI Codex CLI, supports thread recovery (thread_id), sandbox mode (full-auto), auto-timeout recovery, etc.

All commands (/goon, /!, /new, /cc, etc.) support multi-Agent routing without additional configuration.

Security Notes

Sensitive fields (clientSecret, dingToken, defaultDingToken, apiKeyCfg[].apiKey) support $ENV:VAR_NAME references to environment variables, e.g. "clientSecret": "$ENV:DING_SECRET"
config.json and settings-ding.json are written with 600 permissions
/bash is restricted to owner/admin; all commands are audited in ~/.cc-ding/{clientId}/bash-audit.log

Data Storage

All data is stored under ~/.cc-ding/{clientId}/:

Type	Path
Sessions	`{MD5}/.sessions/{claudeSessionId
Tasks	`{MD5}/.tasks/{timestamp}/task.{json,log}`
Cron jobs	`cron.json`
Image cache	`{MD5}/.images/`
User mapping	`user-map.json`

Development

pnpm install
pnpm run lint
pnpm run test
pnpm run build

Star History

Contributors

License

MIT

Name		Name	Last commit message	Last commit date
.husky		.husky
assets		assets
bin		bin
console-web		console-web
docs		docs
resource		resource
scripts		scripts
src		src
test		test
.blacklintrc		.blacklintrc
.dockerignore		.dockerignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.mocharc.yml		.mocharc.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
docker-entrypoint.sh		docker-entrypoint.sh
ecosystem.config.js		ecosystem.config.js
eslint.config.js		eslint.config.js
index.ts		index.ts
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

cc-ding

中文 | 简体中文

交流群

目录

快速开始

安装

初始化

编辑配置

启动

命令参考

会话

任务

定时任务

文件操作

管理命令（仅 owner）

Web Console

启动 Console

端口约定

登录

功能

URL 深度链接

配置说明

配置文件示例

配置项速查

多 Agent 架构（v1.1.0）

安全说明

数据存储

开发

English

Community

Table of Contents

Quick Start

Install

Initialize

Edit Config

Start

Commands

Session

Task

Scheduled

File Operations

Admin (owner only)

Web Console

Start Console

Port Conventions

Login

Features

URL Deep Links

Configuration

Configuration Example

Config Quick Reference

Multi-Agent Architecture (v1.1.0)

Security Notes

Data Storage

Development

Star History

Contributors

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages