CLAUDE_CONFIG_DIR

Bin大约 4 分钟

CLAUDE_CONFIG_DIR

在单台服务器上通过 `CLAUDE_CONFIG_DIR` 实现 Claude Code CLI 多 Agent 隔离（SDK 实战）

目标读者

使用 Claude Code CLI
使用 Claude Agent SDK（Python）
希望在 同一台服务器 上运行 多个逻辑隔离的 Claude Agent
每个 Agent 拥有 独立的完整配置（skills / settings / CLAUDE.md / 行为边界）

一、问题背景：为什么需要“多 Agent 隔离”

在实际工程中，我们经常希望：

Excel Agent：只处理 Excel 相关能力
Word Agent：只处理 Word 相关能力
每个 Agent：
- 只暴露自己的配置目录（skills / CLAUDE.md / settings 等）
- 不共享 system prompt / CLAUDE.md / skill 集
- 不会“串技能”或误调用

但现实约束是：

不希望每个 Agent 都单独一台服务器
希望 同一 FastAPI 服务 / 同一机器 上完成隔离

二、Claude Code CLI 的关键能力：`CLAUDE_CONFIG_DIR`

Claude Code CLI 原生支持通过环境变量指定配置根目录：

CLAUDE_CONFIG_DIR=/path/to/.claude-config

该目录下通常包含：

.claude-config-xxx/
├─ CLAUDE.md
├─ settings.json
└─ skills/
   └─ <skill_name>/
      ├─ SKILL.md
      └─ settings.json

核心事实：

Claude Code 在启动 Agent Runtime 时，只会从 CLAUDE_CONFIG_DIR 加载一次完整配置（含 CLAUDE.md / settings / skills）。

这为“Agent 隔离”提供了天然的切入点。

三、整体方案设计（一句话版）

通过 SDK 在创建 Claude Agent 时，传入不同的 CLAUDE_CONFIG_DIR，使 Claude Code CLI 在逻辑上变成不同的 Agent。

关键点：

每个 Agent 对应一个 独立的 .claude-config-* 目录
SDK 层通过 env={"CLAUDE_CONFIG_DIR": ...} 注入
Claude Agent Runtime 只加载该目录下的完整配置
不会看到其他 Agent 的配置与 skill

四、目录结构设计（实战示例）

agent/
├─ .claude-config-excel
│  └─ skills
│     └─ excel
│        ├─ SKILL.md
│        └─ settings.json
├─ .claude-config-word
│  └─ skills
│     └─ word
│        ├─ SKILL.md
│        └─ settings.json
├─ .venv
└─ chat.py

Excel Skill（示例）

---
name: Excel Skill
description: Respond with a fixed marker to confirm the skill was invoked.
user-invocable: true
---

When invoked, respond with exactly:
SKILL_EXCEL_OK

Do not add any other text.

Word Skill（示例）

---
name: Word Skill
description: Respond with a fixed marker to confirm the skill was invoked.
user-invocable: true
---

When invoked, respond with exactly:
SKILL_WORD_OK

Do not add any other text.

五、FastAPI + Claude Agent SDK 实现方式

关键设计点

每个请求可以传入自己的 claude_config_dir
SDK 创建 ClaudeAgentOptions 时注入 env
Claude Agent 从该目录加载 skills

核心代码（关键片段）

options_kwargs = {
    "system_prompt": "You are a concise assistant.",
    "setting_sources": ("user",),
    "cwd": payload.repo_root or str(Path(__file__).parent.resolve()),
    "allowed_tools": [],
}

if payload.claude_config_dir:
    options_kwargs["env"] = {
        "CLAUDE_CONFIG_DIR": payload.claude_config_dir
    }

options = ClaudeAgentOptions(**options_kwargs)

六、运行服务

uvicorn chat:app --host 0.0.0.0 --port 8000 --reload

七、验证隔离效果（关键实验）

1️⃣ Excel Agent

curl -N -X POST http://127.0.0.1:8000/chat-stream \
  -H "Content-Type: application/json" \
  -d '{
    "question": "/excel",
    "claude_config_dir": "/Users/xiaoxu/Desktop/agent/.claude-config-excel",
    "debug": true
  }'

结果：

SKILL_EXCEL_OK

2️⃣ Word Agent

curl -N -X POST http://127.0.0.1:8000/chat-stream \
  -H "Content-Type: application/json" \
  -d '{
    "question": "/word",
    "claude_config_dir": "/Users/xiaoxu/Desktop/agent/.claude-config-word",
    "debug": true
  }'