configure

OrchestKit 配置

用于自定义 OrchestKit 安装的交互式设置。

快速开始

configure
configure mcp memory

参数解析

PRESET = "$ARGUMENTS[0]"   # Optional preset name or subcommand, e.g., "mcp"
TARGET = "$ARGUMENTS[1]"   # Optional target, e.g., "memory"
# If no arguments, run interactive wizard.
# $ARGUMENTS is the full string (CC 2.1.59 indexed access)

完成意味着已写入 ~/.claude/plugins/orchestkit/config.json，用户已查看第 11 步的预览，并且已提示用户运行 /reload-plugins。 预算：每步最多调用一次 AskUserQuestion，最多 11 步；到达完成点或首次触及上限时，立即停止并报告。

第 1 步：选择预设

使用 AskUserQuestion：

预设	技能	Agent	Hooks	描述
完整	全部	全部	全部	全部内容
标准	全部	0	全部	技能，不含 Agent
精简	28	0	全部	仅包含核心内容（测试、安全、规划）
仅 Hooks	0	0	全部	安全、效率和团队协作 Hooks
Monorepo	全部	全部	全部	完整版 + Monorepo 检测

实时数量：运行 claude plugin details ork（截至 2026-09-25，共有 107 个技能、36 个 Agent）。

第 2 步：自定义技能类别

可用类别：

• AI/ML（28 个技能）
• 后端（16 个技能）
• 前端（9 个技能）
• 测试（14 个技能）
• 安全（7 个技能）
• DevOps（5 个技能）
• 规划（7 个技能）
• 工作流（5 个技能）

第 3 步：自定义 Agent

产品 Agent（2 个）：

• market-intelligence
• product-strategist

技术 Agent（17 个）：

• backend-system-architect
• frontend-ui-developer
• database-engineer
• llm-integrator
• workflow-architect
• data-pipeline-engineer
• test-generator
• code-quality-reviewer
• security-auditor
• security-layer-auditor
• debug-investigator
• system-design-reviewer
• python-performance-engineer
• frontend-performance-engineer
• monitoring-engineer
• event-driven-architect
• infrastructure-architect

运维 Agent（6 个）：

• ci-cd-engineer
• deployment-manager
• git-operations-engineer
• release-engineer
• ai-safety-auditor
• multimodal-specialist

研究 Agent（4 个）：

• web-research-analyst
• market-intelligence
• design-system-architect
• demo-producer

第 4 步：配置 Hooks

安全 Hooks（始终启用）：

• git-branch-protection
• file-guard
• redact-secrets

可切换的 Hooks：

• 效率（自动批准、日志记录）
• 质量门禁（覆盖率、模式）
• 团队协作（锁、冲突）
• 通知（桌面、声音）

CC 2.1.49 托管设置： OrchestKit 随插件附带默认 Hook 权限的 settings.json。这些是托管默认值——用户可以在项目设置或用户设置中覆盖。企业管理员可以通过托管配置文件锁定托管设置。

CC 2.1.111 — 清理过于宽泛的 Bash 权限： 从 2.1.111 开始，带有 glob 模式（ls:*、head:*、grep:*、wc:*、find:* 等）的只读 Bash 命令默认不再触发权限提示。如果你的 .claude/settings.local.json 中添加了显式的 Bash(ls:*) / Bash(grep:*) 形式的允许规则，以屏蔽旧版提示，那么这些规则现在已多余。内置的 /less-permission-prompts 技能会扫描你的对话记录并提出精简差异——每个项目运行一次，每个用户配置文件运行一次，然后提交接受的子集。已提交的 OrchestKit src/settings/ork.settings.json 已经很精简（允许项包括 Read、Glob、Grep 和少量 MCP 条目），无需更改。

CC 2.1.129 — Bash(mkdir *) / Bash(touch *) 允许规则现在适用于项目内路径： 以前，这些规则用于相对于项目的路径时会被静默拒绝；现在会按文档说明生效。枚举显式子路径的变通条目（Bash(mkdir:./src/*) 等）可以合并回规范的 glob 形式。参见 references/cc-version-settings.md § CC 2.1.129。 CC 2.1.157 — 插件自动加载 + 工作流触发控制：.claude/skills 中的插件会自动加载（无需 marketplace）；claude plugin init <name> 会在该目录下创建插件脚手架。在 /config 中切换“Workflow keyword trigger”，以及在关键词后立即按退格键，可以阻止单独输入“workflow”或“ultracode”时启动动态工作流。claude agents 会遵循 settings.json 中的 agent 字段，也可使用 --agent <name> 覆盖。

**CC 2.1.160 — 写入启动文件和构建配置时显示提示：**Claude 写入 Shell 启动文件（.zshenv/.zlogin/.bash_login、~/.config/git/），或在 acceptEdits 模式下写入可授予代码执行权限的构建工具配置（.npmrc、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/）之前，会要求批准。这些是安全默认设置；请谨慎批准，不要预先允许。

**CC 2.1.141 — 使用 ANTHROPIC_WORKSPACE_ID 设置工作负载身份联合：**通过 Anthropic 的 WIF 流程为无头/CI Agent（例如 ci-sentinel、bare-eval）进行身份验证时，如果联合规则涵盖多个工作区，请设置 ANTHROPIC_WORKSPACE_ID，将生成的令牌限定到一个工作区。否则，多工作区规则会生成不限定工作区的令牌。

**CC 2.1.142 — 远程 MCP 使用 MCP_TOOL_TIMEOUT：**现在，单个请求的超时时间会实际应用于远程 HTTP/SSE MCP 服务（此前无论配置值为何，都会限制在 60 秒）。对于确实会运行超过 60 秒的长轮询工具（如 NotebookLM studio_status、知识库导入、索引重建），请调高该值（例如 MCP_TOOL_TIMEOUT=180000），避免它们静默超时并自动跳过。

CC 2.1.169 — 安全模式 + 策略强制执行修复：--safe-mode（或 CLAUDE_CODE_SAFE_MODE=1）会启动 CC，并禁用所有自定义项——CLAUDE.md、插件、技能、钩子、MCP 服务——这是在提交 Bug 前快速排查“是否由 ork（或任何插件）导致此问题”的最快方式。企业托管 MCP 策略（allowedMcpServers/deniedMcpServers）现在会在重新连接、IDE 输入的配置、安装后首次会话中的 --mcp-config 服务，以及远程设置加载前强制执行——如果你的组织设置了这些策略，此前可正常工作的未列出服务现在可能会被（正确地）拦截。不受信任的项目设置无法再在未经信任确认的情况下设置 OTEL 客户端证书路径。可自托管的运行器新增了 post-session 生命周期钩子（会话结束后、工作区删除前），可用于保存未提交的工作或导出日志；此外还提供可配置的 SIGTERM→SIGKILL 等待时间（默认为 5 秒）。

CC 2.1.166 — fallbackModel 设置（最多 3 个模型）：现在，fallbackModel 设置最多接受 3 个模型；当主模型过载或不可用时，会按顺序尝试这些模型。--fallback-model 现在也适用于交互式会话（不再仅限于无头会话）。为较长的 ork:implement / ork:brainstorm 运行设置此项，这样主模型过载时就会切换到下一个模型，而不是让运行停滞。此设置扩展了 references/cc-version-settings.md 中的 2.1.152 回退说明。

CC 2.1.181 — 使用 /config key=value 设置一次性配置：可直接在提示词中设置任意单项配置——/config thinking=false、/config model=opus——无需打开 /config 菜单或手动编辑设置文件。适用于交互式会话、-p 和 Remote Control。这是设置一次性、临时配置变更的快捷方式。它不能替代持久化自动化：若要实现“每当 X 发生时，就执行 Y”，仍需要在 settings.json 中配置钩子（运行环境负责执行钩子；/config 只会写入设置值）。使用 /config key=value 立即切换设置；若要让更改在每次会话中自动生效，请使用此技能的钩子流程。参见 references/cc-version-settings.md § CC 2.1.181。

步骤 5：配置 MCP（可选）

所有 4 个 MCP 均默认启用。Tavily 需要 API 密钥。

MCP	用途	默认状态	要求
context7	库文档	已启用	无
memory	跨会话持久化	已启用	无
sequential-thinking	为子 Agent 提供结构化推理	已启用	无
tavily	网页搜索 + 提取	已启用	API 密钥（免费层级：app.tavily.com）

为何启用？ OrchestKit 附带 30 多个 Sonnet/Haiku 子 Agent。Opus 5.5、Sonnet 5 和 Haiku 5.5 原生具备思考能力（默认开启自适应思考），因此 sequential-thinking 对固定使用较旧模型（例如 Haiku 4.5）的子 Agent 最有用，因为这类模型需要显式设置 budget_tokens。如果 haiku 仍解析为 Haiku 4.5（CC 低于 2.1.293、Bedrock、Vertex、Foundry），则所有 model: haiku 子 Agent 都会受到影响。Tavily 供特定 Agent 使用（参见 Agent frontmatter 中的 mcpServers）。当开销超过上下文的 10% 时，CC 的 MCPSearch 会自动延迟加载架构，因此会自动管理令牌成本。

后台 Agent： 后台子 Agent 无法使用 MCP 工具（这是 CC 平台的硬性限制）。需要 MCP 工具的 Agent 必须在前台运行。

已经全局安装了这些 MCP？ 如果 Tavily 或 memory 已经位于你的 ~/.claude/mcp.json 中，请跳过此处的启用操作，以免产生重复条目。OrchestKit Agent 会使用 Claude Code 优先解析到的实例。

选择不使用 claude.ai MCP 服务（CC 2.1.63+）： Claude Code 默认可能会加载来自 claude.ai 的 MCP 服务。若要禁用此功能并仅使用本地配置的 MCP：

export ENABLE_CLAUDEAI_MCP_SERVERS=false

将其添加到你的 shell 配置文件（~/.zshrc 或 ~/.bashrc），以便在各会话间保持设置。此设置仅影响来源于 claude.ai 的 MCP 服务，不会影响 .mcp.json 和 ~/.claude/mcp.json 中本地配置的 MCP。

步骤 6-9：特定 CC 版本的设置

加载详细信息：执行 Read("references/cc-version-settings.md") 查看完整配置选项。

涵盖 CC 2.1.7（MCP 延迟加载阈值、有效上下文窗口）、CC 2.1.20（任务删除、PR 增强、Agent 权限、单体仓库检测、团队分发）、CC 2.1.23（自定义加载动画动词）和 CC 2.1.79（回合时长显示）。

CC 2.1.119：prUrlTemplate（M122）

对于 URL 格式非标准的企业 GitLab / GitHub Enterprise / Bitbucket 安装，可在 ~/.claude/settings.json（或项目级设置）中设置 prUrlTemplate，以覆盖 review-pr / create-pr / fix-issue 中的 URL 构造：

{
  "prUrlTemplate": "https://gitlab.acme.com/{owner}/{repo}/-/merge_requests/{n}"
}

令牌：{host}、{owner}、{repo}、{n}。完整的主机系列表和技能端分支模式，请参见 src/skills/chain-patterns/references/pr-from-platform.md。

步骤 10：Webhook 与遥测配置

配置将会话事件流式传输到 HQ 或你自己的 API。只有一个通道：带 HMAC 签名的 http-sink（批量处理、失败后退避重试、熔断器）。在 .claude/orchestration/config.json 中设置 webhookUrl，并在启动 shell 中导出 ORCHESTKIT_HOOK_TOKEN 后，该通道才会启用。按事件生成原生 HTTP hook 的生成器（通道 1）已在 #3867 中删除；没有任何内容会向 settings.local.json 写入 type: "http" 条目。

AskUserQuestion(questions=[{
  "question": "Set up session telemetry?",
  "header": "Telemetry",
  "options": [
    {"label": "Stream to a webhook", "description": "Analytics events and SessionEnd summaries POST to your endpoint via the HMAC-signed http-sink"},
    {"label": "Skip", "description": "No telemetry, hooks run locally only"}
  ],
  "multiSelect": false
}])

如果选择“流式传输到 webhook”

1. 以纯文本询问 webhook URL。AskUserQuestion 至少需要 2 个选项（CC 架构中的 minItems: 2），且无法接收自由格式的 URL，因此请直接提示：

   你的 webhook 端点 URL 是什么？请回复完整 URL（例如：https://api.example.com/hooks）。

2. 将 webhookUrl 保存到编排配置中：

# File: .claude/orchestration/config.json
saveConfig({ webhookUrl: "<webhook-url>" })

3. 提醒用户设置身份验证令牌：

Set ORCHESTKIT_HOOK_TOKEN in your environment (never in config files):
  export ORCHESTKIT_HOOK_TOKEN=your-secret

执行 Read("references/http-hooks.md")，了解通道历史和 CC 的 URL 验证限制。

步骤 11：预览并保存

提示（CC 2.1.69+）： 保存配置更改后，运行 /reload-plugins，无需重启会话即可激活更改。

提示（CC 2.1.152+）： 如果你在技能目录（个人目录 ~/.claude/skills/ 或项目目录 .claude/skills/，不包括打包在插件中的技能）中编辑或添加了技能，运行 /reload-skills，即可在同一会话中重新扫描并加载这些技能。SessionStart hook 也可以通过返回 reloadSkills: true 执行相同操作。

保存到：~/.claude/plugins/orchestkit/config.json

{
  "version": "1.0.0",
  "preset": "complete",
  "skills": { "ai_ml": true, "backend": true, ... },
  "agents": { "product": true, "technical": true },
  "hooks": { "safety": true, "productivity": true, ... },
  "mcps": { "context7": false, ... }
}

操作员范围设置

有些控制项根本无法随插件一同提供。插件附带的 settings.json 仅支持 agent 和 subagentStatusLine；其他所有内容都会被静默移除，因此 sandbox、permissions.deny 等设置只有放在操作员自己的 ~/.claude/settings.json 中才会生效。ork 曾经声明过完整的 sandbox 配置块（已在 a93ccb735、#3357 中删除），但在其整个生命周期内都未生效。

ork:doctor 的检查 16 会检测该设置是否缺失。可直接粘贴的 JSON 在这里：

Read("references/operator-scope-settings.md")

该参考按照 #3424 分阶段推进，而不是一次性提供一个非启用即全有的配置块：

阶段	内容	适用时机
1 宽松	sandbox.enabled、包含 19 个主机的外传拒绝名单、凭据文件和环境变量拒绝规则、针对 op * / docker * / ssh * 的 excludedCommands 例外项（通配符形式——裸命令名仅匹配不带参数的命令），不设置网络允许名单	首先在正常工作的机器上采用
2 严格	添加 network.allowedDomains，并设置 strictAllowlist: true	仅在阶段 1 稳定运行数天后采用

从阶段 1 开始。 阶段 2 会在没有提示的情况下拒绝所有未列出的主机，并会首先导致 api.github.com、本地主机开发 URL 和遥测数据接收端失效。参考文档详细说明了预期的故障顺序，以及逐行回滚方法。

此技能不会写入操作员的设置文件。是否启用沙箱由操作员决定；回滚只需删除一个键。

VSCode：远程控制（CC 2.1.79+）

VSCode 用户可以运行 /remote-control，将终端会话桥接到 claude.ai/code。这样你就能通过浏览器或手机继续同一会话，适合在离开办公桌时监控长时间运行的配置任务或 Agent 任务。

相关技能

• ork:doctor：诊断配置问题

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
references/presets.md	预设定义
references/mcp-config.md	MCP 配置
references/http-hooks.md	CC 2.1.63+ 可观测性 hook（Langfuse、Datadog、自定义端点）
references/operator-scope-settings.md	用于 ~/.claude/settings.json 的分阶段 sandbox + permissions.deny JSON（#3424）
references/cc-version-settings.md	CC 2.1.7、2.1.20、2.1.23、2.1.79 的版本专属设置