技能医生
- 作者仓库星标 3,406
- 作者仓库 claude-octopus
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @nyldn · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 需要 · Vendor-specific
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Detailed output for troubleshooting
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor --verbose
# Machine-readable output
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor --json
# Combine: specific category + verbose
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor auth --verbose
第 1 步:解析插件根并运行完整诊断
在运行 Octopus 脚本之前使用此解析器。不要假设`~/.claude-octopus/plugin`存在; Windows Git Bash 安装可能不支持稳定的符号链接。将其作为单个 Bash 调用运行。这将运行所有 11 个检查类别并显示格式化报告。
第 2 步:按类别过滤(可选)
如果用户询问特定区域,则过滤:
第 3 步:检查并安装依赖项
运行依赖项检查器以查找缺少的 CLI、状态行配置和推荐的插件:如果检查报告缺少依赖项,请主动安装它们:此操作会自动安装:Codex CLI、Gemini CLI、jq 和状态行解析器。对于插件(claude-mem、document-skills),它会打印用户必须手动运行的`/plugin install`命令。
第 5 步:交互式修复(对于可修复的问题必须执行)
运行诊断后,如果发现任何可修复的问题,您必须使用 AskUserQuestion 来提供修复。不要只是打印说明——主动提出执行它们。 RTK 未安装:如果用户选择安装,运行它,然后提供挂钩设置。在 macOS/Linux 上已安装 RTK 但未配置挂钩:在 Windows Git Bash 上,不提供 `rtk init -g`。 RTK使用CLAUDE.md注入
> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.
# Environment Doctor
## Overview
Run environment diagnostics across 11 check categories. Identifies misconfigured providers, stale state, broken hooks, and other issues that prevent Claude Octopus from working correctly.
**Core principle:** Detect problems before they surface in workflows.
## When to Use
**Use this skill when:**
- Something isn't working and you're not sure why
- After installing or updating the plugin
- Before a demo or important workflow run
- Checking if providers are properly authenticated
- Verifying scheduler, hooks, or skills are correctly configured
**Do NOT use for:**
- First-time setup (use `/octo:setup` — it guides configuration)
- Project workflow status (use `/octo:status`)
- Debugging application code (use `/octo:debug`)
## The Process
### Step 1: Resolve Plugin Root and Run Full Diagnostics
Use this resolver before running Octopus scripts. Do not assume
`~/.claude-octopus/plugin` exists; Windows Git Bash installs may not support the
stable symlink. Run this as a single Bash call.
```bash
OCTO_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
OCTO_PLUGIN_ROOT="${HOME}/.claude-octopus/plugin"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]] && command -v octopus >/dev/null 2>&1; then
OCTO_BIN="$(command -v octopus)"
OCTO_PLUGIN_ROOT="$(cd "$(dirname "$OCTO_BIN")/.." && pwd)"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
OCTO_PLUGIN_ROOT="$(
find "${HOME}/.claude/plugins" -type f -path "*/scripts/orchestrate.sh" -print 2>/dev/null \
| sed 's#/scripts/orchestrate.sh$##' \
| grep -E '(nyldn-plugins|claude-octopus|/octo(/[0-9]|$))' \
| sort \
| tail -1
)"
fi
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
echo "Claude Octopus plugin root not found. Reinstall the octo plugin, then retry /octo:doctor."
exit 1
fi
mkdir -p "${HOME}/.claude-octopus"
ln -sfn "$OCTO_PLUGIN_ROOT" "${HOME}/.claude-octopus/plugin" 2>/dev/null || true
export OCTO_PLUGIN_ROOT
cd "$OCTO_PLUGIN_ROOT" && bash scripts/orchestrate.sh doctor
```
This runs all 11 check categories and displays a formatted report.
### Step 2: Filter by Category (Optional)
If the user asks about a specific area, filter:
```bash
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor providers
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor auth
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor config
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor state
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor smoke
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor hooks
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor scheduler
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor skills
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor conflicts
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor agents
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor recurrence
```
### Step 3: Check & Install Dependencies
Run the dependency checker to find missing CLIs, statusline config, and recommended plugins:
```bash
bash "${HOME}/.claude-octopus/plugin/scripts/install-deps.sh" check
```
If the check reports missing deps, offer to install them:
```bash
bash "${HOME}/.claude-octopus/plugin/scripts/install-deps.sh" install
```
This auto-installs: Codex CLI, Gemini CLI, jq, and the statusline resolver. For plugins (claude-mem, document-skills), it prints `/plugin install` commands the user must run manually.
### Step 4: Verbose or JSON Output
```bash
# Detailed output for troubleshooting
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor --verbose
# Machine-readable output
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor --json
# Combine: specific category + verbose
cd "${HOME}/.claude-octopus/plugin" && bash scripts/orchestrate.sh doctor auth --verbose
```
### Step 5: Interactive Remediation (MANDATORY for fixable issues)
After running diagnostics, if ANY fixable issues are found, you MUST use AskUserQuestion to offer fixes. Do NOT just print instructions — offer to execute them.
**RTK not installed:**
```javascript
AskUserQuestion({
questions: [{
question: "RTK saves 60-90% on bash output tokens. Install it now?",
header: "Install RTK",
multiSelect: false,
options: [
{label: "Install via brew (Recommended)", description: "brew install rtk — fast, macOS"},
{label: "Install via cargo", description: "cargo install rtk-token-killer"},
{label: "Skip", description: "Continue without RTK"}
]
}]
})
```
If user chooses install, run it, then offer hook setup.
**RTK installed but hook not configured on macOS/Linux:**
On Windows Git Bash, do not offer `rtk init -g`. RTK uses CLAUDE.md injection
mode there, so report the hook check as skipped.
```javascript
AskUserQuestion({
questions: [{
question: "RTK is installed but the Claude Code hook isn't active. Configure it?",
header: "RTK Hook",
multiSelect: false,
options: [
{label: "Run rtk init -g (Recommended)", description: "Auto-installs Claude Code bash hook on macOS/Linux"},
{label: "Skip", description: "I'll configure it later"}
]
}]
})
```
**Missing providers (Codex/Gemini not installed):**
```javascript
AskUserQuestion({
questions: [{
question: "Some providers are missing. Install them?",
header: "Providers",
multiSelect: true,
options: [
{label: "Codex CLI", description: "npm install -g @openai/codex"},
{label: "Gemini CLI", description: "brew install gemini-cli (macOS)"},
{label: "Skip all", description: "Continue with available providers"}
]
}]
})
```
**Auth expired:**
Offer to run the login command for the expired provider.
**Multiple fixable issues:** Batch them into a single AskUserQuestion with multiSelect where appropriate, rather than asking one at a time.
## Check Categories
| Category | What it checks |
|----------|---------------|
| `providers` | Claude Code version, Codex CLI installed, Gemini CLI installed, Perplexity API key, Ollama local LLM (server + models), circuit breaker status, provider fallback history |
| `auth` | Authentication status for each provider |
| `config` | Plugin version, install scope, feature flags |
| `state` | Project state.json, stale results, workspace writable |
| `smoke` | Smoke test cache, model configuration |
| `hooks` | hooks.json validity, hook scripts |
| `scheduler` | Scheduler daemon, jobs, budget gates, kill switches |
| `skills` | Skill files loaded and valid |
| `conflicts` | Conflicting plugins detection |
| `agents` | Agent definitions, worktree isolation, CLI registration, version compatibility |
| `recurrence` | Failure pattern detection — flags repeated quality gate failures, source hotspots, 48h trends |
| `deps` | Software dependencies — Node.js, jq, Codex/Gemini CLIs, RTK token compression (gain stats + hook status), statusline resolver, recommended plugins |
## Interpreting Results
### Healthy Output
All checks pass — no action needed.
### Common Issues and Fixes
| Issue | Fix |
|-------|-----|
| Codex CLI not found | `npm install -g @openai/codex` or install via `codex login` |
| Gemini CLI not found | Install Gemini CLI from Google |
| Perplexity not configured | `export PERPLEXITY_API_KEY="pplx-..."` (optional) |
| Auth expired | Re-run `codex login` or `gemini login` |
| Circuit breaker OPEN | Provider had 3+ consecutive transient failures — wait for cooldown or check provider status |
| Stale state | Delete `.octo/state.json` and re-initialize |
| Invalid hooks.json | Check `hooks.json` syntax — must be valid JSON |
| RTK not installed | Offer to install: `brew install rtk && rtk init -g` (saves 60-90% tokens). Use AskUserQuestion to offer brew vs cargo install. |
| RTK installed but hook not configured | On macOS/Linux, offer `rtk init -g`; on Windows Git Bash, report skipped because RTK uses CLAUDE.md injection mode |
| RTK gain stats unavailable | Run some bash commands first, then check `rtk gain` to see token savings |
| Conflicting plugins | Uninstall conflicting plugins or adjust scope |
## Integration with Other Skills
| Scenario | Route |
|----------|-------|
| Doctor finds missing provider | Suggest `/octo:setup` to configure |
| Doctor finds stale project state | Suggest `/octo:status` to review |
| Doctor finds hook errors | Guide user to fix hooks.json |
| All checks pass, user still has issues | Suggest `/octo:debug` for deeper investigation |
## Hook Profile
Claude Octopus hooks can run in different profiles to balance cost and coverage.
Current profile: `$OCTO_HOOK_PROFILE` (default: standard)
Available profiles:
- **minimal** — Only session lifecycle and cost tracking hooks (lowest overhead)
- **standard** — All hooks except expensive review/security gates (default)
- **strict** — All hooks enabled including quality and security gates
Override: Set `OCTO_PROFILE=budget|balanced|quality` or `OCTO_DISABLED_HOOKS=hook1,hook2` to fine-tune. Legacy `OCTO_HOOK_PROFILE` still works (minimal→budget, standard→balanced, strict→quality).
## Intensity Profile
The doctor reports the active intensity profile — a single knob controlling hook gating, model selection, phase skipping, and context verbosity.
### What the Doctor Checks
- **Current profile**: `OCTO_PROFILE` value (budget/balanced/quality, default: balanced)
- **Profile source**: env var, legacy `OCTO_HOOK_PROFILE`, or auto-selected from intent
- **Hook gating**: which hooks are enabled/disabled at this profile level
- **Model hints**: which model (sonnet/opus) is recommended for each phase
- **Context verbosity**: compressed/standard/full
### Profile Summary
| Dimension | budget | balanced | quality |
|-----------|--------|----------|---------|
| Hooks | essential only | standard (no quality gates) | all hooks |
| Models | Sonnet everywhere | Sonnet + Opus for synthesis | Opus for most phases |
| Phases | Skip discover if context given | Skip re-discovery | All phases run |
| Context | Compressed | Standard | Full inlining |
## Project Tier Hint
Also report `OCTO_TIER` when set. This is a recommendation hint, not a hard policy.
| Tier | Doctor guidance |
|------|-----------------|
| `prototype` | Prefer faster checks and warn before high-cost provider fanout |
| `mvp` | Use balanced defaults and consensus on risky changes |
| `production` | Recommend full verification, security review, and stricter release gates |
If unset, show `OCTO_TIER=unset` and suggest setting it only when the project has a stable risk profile.
## Remote Session Checks
If `CLAUDE_CODE_REMOTE=true` or `OCTOPUS_REMOTE_SESSION=true`, report:
- remote session detected
- autonomous mode default active when no explicit autonomy is set
- provider probes skipped to conserve time/quota
- full HUD disabled unless `OCTOPUS_REMOTE_STATUSLINE=full`
- provider CLIs may need to be installed in the cloud setup script
Suggest `/octo:setup` only for configuration guidance; do not recommend interactive provider logins inside the remote session.
## Runtime Context
The doctor checks for project-level `RUNTIME.md` — a file that provides project-specific context (API endpoints, env vars, test commands, build steps) to orchestration prompts.
### What the Doctor Checks
- **RUNTIME.md exists** in the project root (also checks `.octopus/RUNTIME.md` and `.claude-octopus/RUNTIME.md`)
- If missing, suggest creating one from the template: `cp "${HOME}/.claude-octopus/plugin/config/templates/RUNTIME.md" ./RUNTIME.md`
- If present, confirm it contains at least one populated section (not just the template defaults)
### Why It Matters
Without a `RUNTIME.md`, orchestration prompts lack project-specific details — leading to generic advice about test commands, environment variables, and build steps. A populated `RUNTIME.md` makes every workflow more accurate.
## Quick Reference
| User Input | Action |
|------------|--------|
| `/octo:doctor` | Run all 11 categories |
| `/octo:doctor providers` | Check provider installation only |
| `/octo:doctor auth --verbose` | Detailed auth status |
| `/octo:doctor --json` | Machine-readable output |
章节与文件索引
按说明文件中的顺序排列。
概述
何时使用
第 1 步:解析插件根并运行完整诊断
第 2 步:按类别过滤(可选)
第 3 步:检查并安装依赖项
文件/命令 -> /octo:* · skills/blocks/codex-host-adapter.md · /octo:setup · /octo:status · /octo:debug · ~/.claude-octopus/plugin · /plugin install · rtk init -g
内容校验值 -> 65576afc7b3d
当前原文的自动摘译,尚未人工审校。
概述
跨 11 个检查类别运行环境诊断。识别错误配置的提供程序、陈旧状态、损坏的挂钩以及其他阻止 Claude Octopus 正常工作的问题。核心原则:在问题出现在工作流程中之前发现问题。
何时使用
在以下情况下使用此技能: 某些功能不起作用,并且您不确定原因 安装或更新插件后 在演示或重要工作流程运行之前 检查提供程序是否经过正确身份验证