Odysseus × Claude Code：用 Skill 包与 Scope 令牌让 Claude 安全接入自托管 AI 工作区

Odysseus 通过 integrations/claude 目录下的 Claude Code Skill 包，让终端里的 Claude Code 会话可以读取/写入自托管工作区的待办、邮件、日历、记忆、文档，并能调试 Cookbook 模型服务。阅读本文后，你将掌握完整的接入流程（令牌 → 下载 Skill → 环境变量 → 调用）、/api/codex/* 受 Scope 约束的 Agent API 全部能力面，以及 Odysseus 如何从服务端到客户端脚本三层强制权限边界、避免 Agent 越权访问用户数据。

一、集成包结构与整体架构

integrations/claude 目录包含 Claude Code 专用的 skill bundle：

integrations/claude/
├── README.md
└── skills/
    └── odysseus/
        ├── SKILL.md                  # Claude Code 读取的技能定义
        └── scripts/
            └── odysseus_api.py       # 调用受 scope 约束的 /api/codex/* API 的 CLI 助手

按 README 的说明，SKILL.md 是 Claude Code 实际加载的技能定义，odysseus_api.py 是一个只依赖标准库（urllib、json）的轻量助手脚本。值得注意的是：运行时所有 Agent 调用走的都是 /api/codex/* 端点——这是 Odysseus 中原生的、带 Scope 门控的 Agent API 命名空间，被所有 Agent 集成共享，codex 这个路径前缀是历史命名。Claude 侧专属的只有一个分发端点 /api/claude/plugin.zip。

从 routes/codex_routes.py 的源码可以确认这一分工。setup_claude_routes() 的 docstring 明确写道：

Claude Code uses the same scope-gated /api/codex/* endpoints at runtime; this router only exists to deliver the skill zip via /api/claude/plugin.zip so the user-facing setup commands stay in the Claude namespace.

也就是说，Claude 集成没有独立的一套数据 API，而是复用 Codex 集成的 Scope 门控路由。

Skill 包是怎么打包下发的？ GET /api/claude/plugin.zip 端点（routes/codex_routes.py）在服务端内存中构造 zip：

1. 先通过 require_authenticated_request 要求请求携带有效凭证（Bearer 令牌）；
2. 只把 integrations/claude/skills/ 子树打进 zip（源码注释说明原因：解压到 ~/.claude/ 时不会把 README.md 等 bundle 元数据污染进 Claude 配置目录）；
3. 跳过 __pycache__ 目录和 .pyc 文件；
4. 以 application/zip 流式返回，Content-Disposition 为 odysseus-claude-skill.zip。

由于解压目标是 ~/.claude/ 且 zip 内路径保留了 skills/odysseus/... 前缀，解压后正好落在 Claude Code 的 skill 搜索路径 ~/.claude/skills/odysseus/ 下。

二、接入流程：令牌、Skill 下载与环境变量

完整接入步骤在 README 的 "User Flow" 中定义，共 5 步：

1. 打开 Odysseus 的 Settings > Integrations；
2. 添加一个 Claude Agent；
3. 复制生成的令牌之后展示的完整设置命令；
4. 打开/关闭允许 Claude 使用的工具开关（即 Scope 开关）；
5. 在 Claude Code 所在的终端中配置两个环境变量并安装 skill 包：

export ODYSSEUS_URL=http://your-odysseus-host:7000
export ODYSSEUS_API_TOKEN=ody_generated_token
mkdir -p ~/.claude
curl -fsSL -H "Authorization: Bearer $ODYSSEUS_API_TOKEN" "$ODYSSEUS_URL/api/claude/plugin.zip" -o /tmp/odysseus-claude-skill.zip
python3 -m zipfile -e /tmp/odysseus-claude-skill.zip ~/.claude/

参数说明：

• ODYSSEUS_URL：Odysseus 实例的基地址，例如 http://127.0.0.1:7000（Odysseus 默认端口 7000）；
• ODYSSEUS_API_TOKEN：在 Settings > Integrations > Add Integration > Claude Agent 中创建的 scoped API 令牌；
• curl -fsSL 中的 -f 让 HTTP 错误（如 403）直接失败而非写入文件，-H "Authorization: Bearer ..." 使用刚生成的令牌完成下载认证；
• 解压命令使用 Python 标准库 zipfile 模块，无需额外安装 unzip。

设置命令是由前端自动生成的。 static/js/settings.js 中定义了 claude 集成类型的完整表单配置，buildSetup 根据当前页面 origin 与令牌实时拼出上面这套命令，并额外附带一条验证命令：

claude: {
  label: 'Claude Agent',
  namePrefix: 'claude agent',
  defaultName: 'Claude Agent',
  pluginPath: '/api/claude/plugin.zip',
  setupDescription: 'Downloads a plugin bundle and registers it.',
  buildSetup: (origin, token) => `export ODYSSEUS_URL=${origin}
export ODYSSEUS_API_TOKEN='${token}'
mkdir -p ~/.claude
curl -fsSL -H "Authorization: Bearer $ODYSSEUS_API_TOKEN" "$ODYSSEUS_URL/api/claude/plugin.zip" -o /tmp/odysseus-claude-skill.zip
python3 -m zipfile -e /tmp/odysseus-claude-skill.zip ~/.claude/
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py capabilities`,
},

前端还会按令牌名称前缀 claude agent 自动识别集成类型（static/js/settings.js）；对旧版无前缀的 scope 令牌则回退按 Codex 处理以兼容。删除集成时调用 DELETE /api/tokens/{id} 吊销令牌。

为什么解压后不需要再"注册"？ 因为 Claude Code 会自动加载 ~/.claude/skills/ 下的一切内容。所以只要终端会话环境里存在 ODYSSEUS_URL 和 ODYSSEUS_API_TOKEN，odysseus skill 在任意 Claude Code 会话中即刻可用。安装完成后可用一条命令验证连通性与权限：

python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py capabilities

三、Scope 授权模型：服务端 403 是最终防线

README 的 "Scope enforcement" 一节是这套集成的安全核心：

The token is scope-gated. Every tool surface is checked server-side in Odysseus, so even if Claude tries to call a forbidden endpoint, it gets 403 until the user enables the matching toggle in Settings > Integrations > Claude Agent.

从 routes/codex_routes.py 的源码可以确认 Scope 映射表：

能力面	读 Scope	写 Scope
Todos	todos:read	todos:write
Email	email:read	email:draft / email:send
Memory	memory:read	memory:write
Calendar	calendar:read	calendar:write
Documents	documents:read	documents:write
Cookbook	cookbook:read	cookbook:launch

授权检查集中在 _scope_owner()（routes/codex_routes.py）：

def _scope_owner(request: Request, allowed: set[str]) -> str:
    """Return the data owner if the caller is allowed for this Codex action."""
    if getattr(request.state, "api_token", False):
        scopes = set(getattr(request.state, "api_token_scopes", []) or [])
        if not scopes.intersection(allowed):
            required = " or ".join(sorted(allowed))
            raise HTTPException(403, f"API token missing required scope: {required}")
        owner = getattr(request.state, "api_token_owner", None)
        if not owner:
            raise HTTPException(403, "API token has no owner")
        return owner
    return require_user(request)

这里有两层保证：其一，Scope 不满足时直接返回 403 且响应体带缺失的 scope 名称；其二，数据归属始终锚定令牌的 owner（api_token_owner），即使授权通过，Agent 也只能看到令牌属主自己的数据——这正是 SKILL.md 中"Keep actions scoped to the token owner"约束的服务端落点。

能力自查端点。 GET /api/codex/capabilities（routes/codex_routes.py）返回当前令牌在每个能力面上的 read/write 布尔值与可用 action 列表，例如：

{
  "integration": "codex",
  "token_scopes": ["todos:read", "todos:write"],
  "tools": {
    "todos": {"read": true, "write": true,
               "actions": ["list", "add", "update", "delete", "toggle_item"]},
    "email": {"read": false, "draft": false, "send": false, ...},
    ...
  },
  "safety": {"email_send_requires_confirmation": true,
              "destructive_actions_should_confirm": true}
}

SKILL.md 要求在使用任何工具面之前先查 capabilities；若 email.read 为 false，就不应尝试读邮件，而应请用户去 Claude Agent 设置里打开对应开关。把 403 视为刻意的设置限制、绝不绕过，是 skill 明文规定的安全规则。

四、SKILL.md：技能定义与路由决策规则

SKILL.md 是 Claude Code 实际加载的行为规范，除了配置与安全约束外，最有价值的部分是"什么请求走什么存储"的决策规则：

• 提醒（"remind me at 5pm to do X"）→ 带 due_date 的 TODO。due_date 本身即提醒——它会通过用户配置的渠道（浏览器/邮件/ntfy）自动触发通知。不要为提醒创建日历事件：名为 "Reminder" 的日历事件只是一个时间块，不会触发任何通知。
• 日程事件（"meeting at 3pm"、"dentist Tuesday 10am"）→ 日历事件。用于会议、预约、重复日程，展示在日历网格上，其提醒在 Odysseus 设置中单独配置。
• 笔记/自由信息（"note that the wifi password is ..."）→ memory 或无 due_date 的 todo（事实存 memory，行动项存 todo）。
• 关于用户的持久事实/偏好 → memory。

判断启发式：用户说"reminder"加时间，默认走 TODO + due_date；只有用户明确说"calendar"、"event"、"meeting"、"appointment"或描述时间区间时才切换到日历。

SKILL.md 的安全章节还列出了明确禁止的旁路手段（"Forbidden Bypass Pattern"）：

• 所有数据访问必须走 /api/codex/* scoped HTTP API；
• 不得用 SSH、Docker、直接 Python import、SQLite 查询、MCP 内部接口、浏览器 Cookie 或本地文件读写 Odysseus 用户数据；
• 不得直接调用 do_manage_notes、邮件 MCP 内部实现或数据库会话，即使存在 shell 访问；
• 未经用户明确指示且令牌不具备发送 scope，绝不允许直接发信。

如果 Agent 发现自己正准备触及 Odysseus 主机/容器、导入应用内部实现、查询数据库或直调 MCP 辅助模块，SKILL.md 要求立即停止，转而请用户打开相应的 Claude Agent 工具开关——因为这些路径会绕过 Odysseus 设置界面与令牌 Scope。

五、数据能力面详解与实战命令

以下命令均基于 skill 包内助手脚本 odysseus_api.py，所有路径均为 ~/.claude/skills/odysseus/scripts/odysseus_api.py。

5.1 Todos 与提醒

Scoped API 端点：

• GET /api/codex/todos
• POST /api/codex/todos

python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py capabilities
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py todos list
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py todos add "Follow up"

支持的 todo action 有 list、add、update、delete、toggle_item（与 capabilities 端点返回的 actions 一致）。

带时间的提醒必须走 POST 形式。 后端会解析自然语言时间，把 due_date 变成结构化提醒（按用户时区锚定），而不是标题里的字符串。todos add TITLE 快捷方式只设置标题，因此凡涉及时间的提醒都应使用通用 POST：

python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py POST /api/codex/todos '{"action":"add","title":"Call dentist","due_date":"tomorrow at 5pm"}'

后端同时接受 ISO 时间戳与自然语言，如 "tomorrow 5pm"、"next Monday 9am"、"in 2 hours"。从源码看，/api/codex/todos 的 list 处理函数最终委托给 Odysseus 的 do_manage_notes（routes/codex_routes.py），且支持 archived、label 查询参数，与主应用的待办数据是同一份存储。

5.2 Email：读取、草稿与发送

Scoped API 端点：

• GET /api/codex/emails?folder=INBOX&limit=10&offset=0&filter=all
• GET /api/codex/emails/{uid}?folder=INBOX

python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py emails list 5
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py emails read UID

若 capabilities 中 email.read 不为 true，不应检查邮件，应请用户开启 Email read 开关。

草稿与发送分三级：

• POST /api/codex/emails/draft-document —— 推荐给 Agent 写邮件回复用：创建一个 language: "email" 的可编辑 Odysseus Document，不触碰 IMAP 与发送链路（助手脚本对应 emails draft-doc JSON_PAYLOAD 子命令）；
• POST /api/codex/emails/draft —— body 匹配 SendEmailRequest（to、cc、bcc、subject、body、body_html、attachments、account_id、in_reply_to、references），需要 email:draft（或 email:send）scope；
• POST /api/codex/emails/send —— 同样的 body，需要 email:send scope，且必须在用户明确指示后才能调用（capabilities 响应中 safety.email_send_requires_confirmation 恒为 true）。

5.3 Memory

• GET /api/codex/memory —— 列出令牌属主的记忆；
• POST /api/codex/memory —— body 形如 {"text": "...", "category": "fact", "source": "user", "session_id": null}，需要 memory:write；
• DELETE /api/codex/memory/{memory_id} —— 删除记忆条目，需要 memory:write。

python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py GET /api/codex/memory
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py POST /api/codex/memory '{"text":"User prefers SI units","category":"preference"}'

5.4 Calendar

• GET /api/codex/calendar/events?start=ISO&end=ISO —— 列出时间窗内事件（需 calendar:read）；
• POST /api/codex/calendar/events —— body 匹配 EventCreate（summary、dtstart、dtend、all_day、description、location、calendar_href、rrule、color），需 calendar:write；
• DELETE /api/codex/calendar/events/{uid} —— 按 uid 删除事件（uid 来自 POST 响应），需 calendar:write。

从源码看（routes/codex_routes.py 中 setup_codex_routes 的端点查找逻辑），这些日历端点并非独立实现，而是通过 _find_endpoint 定位主应用 calendar_router 上 GET/POST /api/calendar/events 的真实处理函数后转发执行——转发前由 _as_owner() 临时把请求用户切换为令牌属主，保证数据隔离语义与主界面完全一致。

5.5 Documents

• GET /api/codex/documents?search=...&limit=50 —— 分页文档库；
• GET /api/codex/documents/{doc_id} —— 获取单个文档；
• POST /api/codex/documents —— body 形如 {"session_id": "...", "title": "...", "content": "...", "language": "markdown"}，需要 documents:write；
• DELETE /api/codex/documents/{doc_id} —— 删除文档，需要 documents:write。

助手脚本对应子命令：documents list [limit]、documents read DOC_ID、documents create JSON_PAYLOAD、documents delete DOC_ID。

5.6 Cookbook serve：调试失败模型的启动

Cookbook 能力面用于复现"人类在 Odysseus → Cookbook 里会做的事"：查看哪些 serve 在运行、tail tmux 输出找出崩溃原因、修改启动命令、重新拉起、杀掉卡住的任务。典型场景是模型服务器起不来（compute-capability 错误、OOM、缺 kernel、attention backend 选错等）。

端点与 Scope：

• GET /api/codex/cookbook/tasks —— 列出活跃的 serve/download/install 任务（sessionId、type、status、repo_id、remoteHost、payload._cmd），需 cookbook:read；
• GET /api/codex/cookbook/servers —— 列出已配置服务器（name、host、port、env 类型与路径、模型目录），需 cookbook:read；
• GET /api/codex/cookbook/cached?host=<NAME> —— 列出指定服务器上已缓存的模型（HF cache + Ollama + 额外 modelDirs），serve 之前应先调用看磁盘上已有什么，需 cookbook:read；
• GET /api/codex/cookbook/presets —— 列出用户保存的 serve 预设（model + host + port + cmd）；用户的预设通常带着可用命令，优先 preset NAME 再考虑自己拼，需 cookbook:read；
• GET /api/codex/cookbook/output/{session_id}?tail=400 —— 读取任务持久化日志文件的最后 N 行（优先）或 tmux 面板（回退）；日志文件在 vllm 崩溃后依然存在，所以能返回真正的 Python traceback 而不是被覆盖的 pane。默认 tail=400，需 cookbook:read；
• POST /api/codex/cookbook/serve —— 启动 serve 任务，body 匹配 ServeRequest：{ repo_id, cmd, remote_host?, ssh_port?, env_prefix?, gpus?, platform? }。cmd 经过严格校验：首段二进制必须在白名单 vllm/python3/sglang/llama-server/ollama/node/npx 内，绝不允许 cd …、source … 前缀或 &&/||/;/$(...) 链式——shell 元字符会被校验器拒绝；venv 激活（env_prefix）由主机保存的设置自动追加，因此只需传裸二进制加参数。需 cookbook:launch；
• POST /api/codex/cookbook/preset/{name} —— 按名称启动保存的预设，复用用户已保存的可用命令与主机，需 cookbook:launch；
• POST /api/codex/cookbook/adopt —— 把外部启动的 tmux 会话注册进 cookbook 跟踪，body：{ tmux_session, model, host?, port? }；当 serve_model 拒绝了 cmd、你回退到直接 ssh+tmux 时使用——不 adopt 的话该会话在 UI 中不可见。需 cookbook:launch；
• POST /api/codex/cookbook/stop/{session_id} —— 杀掉该任务的 tmux 会话，需 cookbook:launch。

# Survey what's running
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py cookbook tasks

# Tail the failing one (sessionId from `cookbook tasks`)
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py cookbook output serve-abc12345 400

# Stop the previous attempt before you try a new flag set
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py cookbook stop serve-abc12345

# Relaunch with new flags. cmd MUST begin with one of the allowlisted binaries.
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py cookbook serve \
  /mnt/HADES/models/Qwen3.5-397B-A17B-AWQ \
  "vllm serve /mnt/HADES/models/Qwen3.5-397B-A17B-AWQ --host 0.0.0.0 --port 8001 --tensor-parallel-size 8 --max-model-len 262144 --gpu-memory-utilization 0.90 --dtype auto --max-num-seqs 8 --trust-remote-code --enable-expert-parallel --enable-auto-tool-choice --tool-call-parser qwen3_coder --reasoning-parser qwen3" \
  pewds@192.168.1.12

调试循环模式（SKILL.md 原文总结）：

1. cookbook tasks → 找到失败的 sessionId；
2. cookbook output SID 600 → 读最后 600 行，定位真正的根因行（错误常在可见尾部之上，因为 tmux 回滚缓冲已滚动——若报错提示"above"就请求更大的 tail）；
3. cookbook stop SID → 重启前先杀掉上一次尝试；两个 serve 撞同一个 --port 会冲突；
4. cookbook serve repo "new cmd" → 尝试下一组参数，等约 20 秒后对新 sessionId 执行 cookbook output。

该能力面强制的硬性限制：cookbook serve 的 cmd 白名单 + shell 元字符拒绝（只能跑模型服务器二进制，不能跑任意 shell）；cookbook stop 只接受匹配 [a-zA-Z0-9_-]+ 的任务 sessionId。同时 SKILL.md 特别提醒：Agent 确实能拉起占用 GPU 的长驻进程，所以重启前必须先 cookbook stop 上一次尝试，并用 cookbook tasks 检查同端口冲突。从源码看，cookie 会话（非 API 令牌）调用 cookbook 面时还会被 _require_cookbook_scope 额外要求 admin 权限（routes/codex_routes.py），因为这些端点会暴露主机拓扑、任务日志、tmux 命令与模型服务控制——对 Agent 集成则一律以令牌 scope 为准。

六、odysseus_api.py 助手脚本的实现要点

odysseus_api.py 只有约 200 行、零第三方依赖，其完整命令面（_usage 输出）为：

usage:
  odysseus_api.py capabilities
  odysseus_api.py todos list
  odysseus_api.py todos add TITLE
  odysseus_api.py emails list [limit]
  odysseus_api.py emails read UID
  odysseus_api.py emails draft-doc JSON_PAYLOAD
  odysseus_api.py documents list [limit]
  odysseus_api.py documents read DOC_ID
  odysseus_api.py documents create JSON_PAYLOAD
  odysseus_api.py documents delete DOC_ID
  odysseus_api.py cookbook tasks
  odysseus_api.py cookbook servers
  odysseus_api.py cookbook cached [HOST]
  odysseus_api.py cookbook presets
  odysseus_api.py cookbook output SESSION_ID [tail]
  odysseus_api.py cookbook serve REPO_ID 'CMD' [REMOTE_HOST]
  odysseus_api.py cookbook preset NAME
  odysseus_api.py cookbook adopt SESSION_ID MODEL [HOST] [PORT]
  odysseus_api.py cookbook stop SESSION_ID
  odysseus_api.py METHOD /api/codex/path [json-body]

关键实现细节：

• 配置校验（_config()）：ODYSSEUS_URL 会 rstrip("/") 后使用，避免拼接出双斜杠；任一环境变量缺失时打印缺失项名称并以退出码 2 终止，不猜测凭据；
• 客户端路径门控（odysseus_api.py）：通用 METHOD path [json-body] 形式下，路径不以 /api/codex/ 开头会直接拒绝（refusing non-/api/codex path; use scoped Odysseus integration endpoints only），退出码 2。这是客户端侧的第一道防旁路——即便 Agent 想借这个脚本访问别的 API，脚本本身就不放行；
• 认证与超时：请求头固定 Accept: application/json 与 Authorization: Bearer <token>；带 body 时先做 JSON 解析校验（畸形 JSON 直接报 invalid json body）；urlopen 超时 20 秒；
• 错误处理：HTTPError 会把服务端响应体（例如 403 的 scope 缺失提示）打到 stderr 并返回 1；网络层 OSError 返回 1。Claude Code 可以据此判断是"权限被限制"（应引导用户开开关）还是"网络/服务不可达"；
• URL 编码：cookbook cached、cookbook preset 的子命令对 host/preset 名称做了 urllib.parse.quote 编码，cookbook adopt 的 port 会强制 int() 转换。

需要说明的一个细节：脚本的模块 docstring 与缺参提示里保留的是 "Codex" 字样（如 missing ODYSSEUS_URL; create a Codex Agent token ...），因为该脚本与 Codex 集成的 integrations/codex/scripts/odysseus_api.py 同源共享——这与"scope-gated agent API 统一位于 /api/codex/*"的架构是一致的。

七、与 Codex 集成的关系：同一套 API，不同的交付方式

integrations 目录下并列存在 codex 集成，两者共享同一套 /api/codex/* Scope API，差异仅在交付与安装方式：

	Claude 集成	Codex 集成
分发端点	GET /api/claude/plugin.zip	GET /api/codex/plugin.zip
zip 内容	仅 skills/ 子树（避免污染 ~/.claude）	整个 integrations/codex bundle（含 README 等元数据）
安装位置	~/.claude/，解压即生效	~/plugins/ + 写入 ~/.agents/plugins/marketplace.json + codex plugin add odysseus@personal
验证命令	~/.claude/skills/odysseus/scripts/odysseus_api.py capabilities	~/plugins/odysseus/scripts/odysseus_api.py capabilities

从 setup_claude_routes 与 setup_codex_routes（routes/codex_routes.py）的对照可以确认：两个 zip 端点的打包逻辑几乎相同，区别正在于 Claude 版刻意只取 skills/ 子树，且保留相对 bundle_root 的路径，让解压落点与 Claude Code 的 skill 自动发现机制严丝合缝。

八、小结

Odysseus 的 Claude Code 集成可以用三条主线概括：

1. 交付：Settings > Integrations 生成 scoped 令牌 → 前端自动生成含 /api/claude/plugin.zip 的 curl 命令 → 解压到 ~/.claude/ 即被 Claude Code 自动发现，无需任何注册步骤；
2. 能力：SKILL.md 定义了提醒/日程/记忆/邮件/文档/Cookbook 六类意图的路由规则与全部 /api/codex/* 端点用法，odysseus_api.py 提供了零依赖的完整 CLI 命令面，并内置路径前缀门控；
3. 安全：_scope_owner 在服务端逐端点检查 scope 并锁定令牌属主数据，403 即设置界面的限制结果；SKILL.md 与脚本双层禁止 SSH/DB/MCP 内部旁路，cookbook 面额外施加 cmd 白名单与 shell 元字符拒绝。

这套"Skill 包 + scoped 令牌 + 服务端 scope 门控"的组合，使得 Claude Code 这类外部 Agent 能在不接触 Odysseus 内部存储的前提下，按用户在设置界面逐项勾选的粒度安全地操作自托管工作区数据。