使用说明
克劳德代理人
一个自托管的Docker容器，为Claude Code提供web UI，支持基于聊天的AI辅助工作流程、Webhook、计划任务和MCP集成。
特性
- 🐳 Docker化 -使用单个容器在任何地方运行
- 💬 网络聊天界面 -与Claude聊天的漂亮终端风格UI
- 📁 持久会话 -所有对话和设置都已保存
- 🔧 Claude代码集成 -完全访问Claude Code CLI功能
- 📂 可配置工作区 -挂载任何目录供Claude使用
- 🔐 OIDC身份验证 -使用OpenID Connect（PocketID、Keycloak等）进行安全访问
- 🔄 工作流 -由日程表、webhook或两者触发的自动化任务
- 🔑 API令牌 -安全访问API以实现自动化和集成
- 🤖 MCP 服务器 -AI工具集成的模型上下文协议支持
快速开始
先决条件
- Docker和Docker Compose
- 无烟煤API键(在这里买一个)
1.克隆和配置
git clone https://github.com/NickLewanowicz/claude-agent.git
cd claude-agent
# Copy the example environment file
cp env.example .env
# Edit .env and add your Anthropic API key
nano .env
2.使用Docker Compose运行
docker-compose up -d
3.访问用户界面
打开 http://localhost:3000 在您的浏览器中。
配置
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
ANTHROPIC_API_KEY |
您的Anthropic API密钥（必需） | - |
CLAUDE_MODEL |
要使用的Claude模型 | claude-sonnet-4-20250514 |
OIDC_ENABLED |
启用OIDC身份验证 | false |
OIDC_ISSUER_URL |
OIDC提供商URL（例如。， https://id.example.com) |
- |
OIDC_CLIENT_ID |
OIDC客户端ID | - |
OIDC_CLIENT_SECRET |
OIDC客户端机密 | - |
OIDC_REDIRECT_URI |
OAuth回调URL | http://localhost:4000/auth/callback |
FRONTEND_URL |
重定向的前端URL | http://localhost:5173 |
SESSION_SECRET |
会话Cookie的秘密 | （随机） |
卷装载
容器使用两个体积：
| 路径 | 目的 |
|---|---|
/data |
会话、工作流、令牌和Claude配置的持久存储 |
/workspace |
Claude可以访问和修改的工作目录 |
工作流
工作流是自动化的Claude任务，可以通过以下方式触发：
- 日程 -按照cron时间表运行（例如，每天上午9点）
- 网络钩子 -由具有API令牌身份验证的HTTP请求触发
- 两者 -支持日程表和webhook触发器
创建工作流
- 打开Claude Agent用户界面
- 点击 工作流 在侧边栏中
- 点击 创建工作流
- 配置：
- 名称和说明
- 提示执行
- 触发器类型（计划、webhook或两者）
- Cron表达式（用于计划工作流）
Cron表达式示例
| 表达式 | 描述 |
|---|---|
0 9 * * * |
每天上午9:00 |
*/15 * * * * |
每15分钟 |
0 0 * * 1 |
每周一午夜 |
0 0 1 * * |
每月的第一天 |
通过Webhook触发
curl -X POST "https://agent.example.com/webhook/{workflow-id}" \
-H "Authorization: Bearer clag_your-api-token" \
-H "Content-Type: application/json" \
-d '{"key": "value"}'
答复：
{
"success": true,
"runId": "abc123",
"sessionId": "xyz789",
"message": "Workflow triggered successfully"
}
API令牌
API令牌允许对Claude Agent功能进行编程访问。
创建令牌
- 打开Claude Agent用户界面
- 点击 设置 在侧边栏中
- 去 API令牌 标签
- 点击 创建API令牌
- 选择所需的范围
- 复制令牌（它只显示一次！）
令牌范围
| 范围 | 描述 |
|---|---|
workflows:read |
读取工作流及其运行历史记录 |
workflows:write |
创建、更新和删除工作流 |
workflows:trigger |
通过webhook触发工作流 |
sessions:read |
阅读聊天会话 |
sessions:write |
创建和管理聊天会话 |
resources:read |
阅读技能、代理和命令 |
mcp:access |
访问MCP服务器 |
使用代币
将令牌包含在 Authorization 头球
curl -X POST "https://agent.example.com/webhook/abc123" \
-H "Authorization: Bearer clag_your-api-token" \
-H "Content-Type: application/json" \
-d '{}'
认证
OIDC设置
Claude Agent支持OIDC身份验证以实现安全访问。兼容：
- 口袋 ID
- 钥匙锁
- 身份验证0
- 任何标准OIDC提供商
PocketID的示例配置：
OIDC_ENABLED=true
OIDC_ISSUER_URL=https://id.example.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=https://agent.example.com/auth/callback
FRONTEND_URL=https://agent.example.com
MCP服务器（模型上下文协议）
Claude Agent包含一个MCP服务器，该服务器公开了用于管理工作流、会话和资源的工具。这允许AI代理（如Claude Desktop）与您的Claude Agent实例进行交互。
可用工具
工作流管理
list_workflows-列出所有工作流get_workflow-获取工作流详细信息create_workflow-创建新工作流update_workflow-更新工作流delete_workflow-删除工作流toggle_workflow-启用/禁用工作流toggle_schedule_trigger-启用/禁用计划触发器toggle_webhook_trigger-启用/禁用webhook触发器run_workflow-立即运行工作流get_workflow_runs-获取跑步历史记录get_cron_presets-获取常用的cron预设
会话管理
list_sessions-列出所有聊天会话get_session-获取包含消息的会话create_session-创建新会话
资源
list_resources-列出所有技能、代理、命令list_skills-列出可用技能list_agents-列出可用代理list_commands-列出可用命令
执行
run_prompt-直接执行Claude提示符
运行MCP服务器
cd backend
bun run src/mcp.ts
或在Claude Desktop中配置(~/.config/claude/mcp.json):
{
"mcpServers": {
"claude-agent": {
"command": "bun",
"args": ["run", "/path/to/my-agent/backend/src/mcp.ts"],
"env": {
"CLAUDE_DATA_DIR": "/path/to/data",
"ANTHROPIC_API_KEY": "your-api-key"
}
}
}
}
MCP资源
| URI | 描述 |
|---|---|
claude-agent://workflows |
所有工作流列表 |
claude-agent://sessions |
所有聊天会话列表 |
claude-agent://resources |
所有技能、代理、命令列表 |
发展
先决条件
- 包子 （用于后端）
- pnpm （用于前端和工作区管理）
- Node.js 22+
设置
# Install dependencies
pnpm install
# Start development servers
pnpm dev
这运行：
- 后端（Bun）打开
http://localhost:4000 - 前端（Vite）打开
http://localhost:5173
项目结构
my-agent/
├── backend/ # Bun backend server
│ └── src/
│ ├── index.ts # Main server entry
│ ├── claude.ts # Claude Code CLI integration
│ ├── sessions.ts # Session management
│ ├── workflows.ts # Workflow management
│ ├── scheduler.ts # Cron job runner
│ ├── tokens.ts # API token management
│ ├── mcp.ts # MCP server
│ └── auth.ts # OIDC authentication
├── frontend/ # React + Vite frontend
│ └── src/
│ ├── App.tsx # Main app component
│ ├── store.ts # Zustand state management
│ └── components/
│ ├── ChatView.tsx
│ ├── Sidebar.tsx
│ ├── WorkflowsPanel.tsx
│ └── SettingsPanel.tsx
├── Dockerfile # Production container
├── docker-compose.yml # Docker Compose config
└── README.md
建筑
# Build for production
pnpm build
# Build Docker image
docker build -t claude-agent .
运行测试
cd backend
pnpm test
api参考
身份验证端点
| 方法 | 路径 | 描述 |
|---|---|---|
| 得到 | /auth/status |
检查身份验证状态 |
| 得到 | /auth/login |
启动OIDC登录 |
| 得到 | /auth/callback |
OIDC回叫 |
| 职位 | /auth/logout |
注销 |
会话端点
| 方法 | 路径 | 描述 |
|---|---|---|
| 得到 | /api/sessions |
列出会话 |
| 职位 | /api/sessions |
创建会话 |
| 得到 | /api/sessions/:id |
获取会话 |
| 删除 | /api/sessions/:id |
删除会话 |
| 职位 | /api/sessions/:id/chat |
发送消息（SSE） |
工作流端点
| 方法 | 路径 | 描述 |
|---|---|---|
| 得到 | /api/workflows |
列出工作流 |
| 职位 | /api/workflows |
创建工作流 |
| 得到 | /api/workflows/:id |
获取工作流 |
| 补丁 | /api/workflows/:id |
更新工作流程 |
| 删除 | /api/workflows/:id |
删除工作流 |
| 职位 | /api/workflows/:id/toggle |
启用切换 |
| 职位 | /api/workflows/:id/toggle-schedule |
切换计划触发器 |
| 职位 | /api/workflows/:id/toggle-webhook |
切换webhook触发器 |
| 职位 | /api/workflows/:id/regenerate-secret |
重新生成webhook密钥 |
| 职位 | /api/workflows/:id/run |
马上跑 |
| 得到 | /api/workflows/:id/runs |
获取跑步历史记录 |
| 职位 | /api/workflows/validate-cron |
验证cron表达式 |
| 得到 | /api/workflows/presets |
获取cron预设 |
| 职位 | /webhook/:id |
触发工作流 （需要API令牌） |
令牌端点
| 方法 | 路径 | 描述 |
|---|---|---|
| 得到 | /api/tokens |
列出令牌 |
| 职位 | /api/tokens |
创建令牌 |
| 得到 | /api/tokens/:id |
获取令牌 |
| 补丁 | /api/tokens/:id |
更新令牌 |
| 删除 | /api/tokens/:id |
删除令牌 |
| 得到 | /api/tokens/scopes |
获取可用范围 |
资源端点
| 方法 | 路径 | 描述 |
|---|---|---|
| 得到 | /api/resources |
获取所有资源 |
| 得到 | /api/resources/skills |
列出技能 |
| 得到 | /api/resources/agents |
列出代理 |
| 得到 | /api/resources/commands |
列出命令 |
建筑
┌─────────────────────────────────────────────────────────────────┐
│ Docker Container │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────────────────────────────┐ │
│ │ React │───▶│ Bun Server │ │
│ │ Frontend │◀───│ (REST API + SSE + Scheduler) │ │
│ └─────────────┘ └──────────────┬──────────────────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌─────▼─────┐ ┌─────▼─────┐ │
│ │ Claude Code │ │ Scheduler │ │ MCP Server│ │
│ │ CLI │ │ (Cron) │ │ (stdio) │ │
│ └─────────────┘ └───────────┘ └───────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Volumes: │
│ /data - Sessions, workflows, tokens, .claude │
│ /workspace - Working directory for Claude │
└─────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Webhooks │ │ MCP Clients │
│ (External) │ │ (AI Agents) │
└─────────────┘ └─────────────┘
路线图
- [x] 基本聊天界面
- [x] 会话管理
- [x] Claude Code CLI集成
- [x] OIDC身份验证
- [x] 统一工作流（日程+webhook）
- [x] API令牌管理
- [x] MCP服务器
- []技能系统（可重复使用的提示/动作）
- []代理人（专业助理）
- []电子邮件/通知集成
- []多型号支持
- []工作流负载模板
- []重试策略
许可证
麻省理工学院
