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

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

【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseus

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.zipso 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，odysseusskill 在任意 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 gets403until the user enables the matching toggle in Settings > Integrations > Claude Agent.

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

授权检查集中在_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:sendscope，且必须在用户明确指示后才能调用（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，差异仅在交付与安装方式：

从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 内部存储的前提下，按用户在设置界面逐项勾选的粒度安全地操作自托管工作区数据。

【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseus