如何把 Claude Code 接入 Odysseus：API Token、技能包安装与权限范围

如果你的 Odysseus 实例已经在运行，并希望在 Claude Code 的终端会话里直接读写 Odysseus 的数据（todos、邮件、记忆、日历、文档），这篇文档给出的操作路径是：在 Odysseus 的 Settings > Integrations 中创建一个 Claude Agent 集成生成 API Token，把 Odysseus 提供的 odysseus 技能包安装到 ~/.claude/ 下，再通过 capabilities 端点核对 Token 实际拥有的权限范围。Claude Code 会自动加载 ~/.claude/skills/ 下的技能，因此安装完成后，任何带有 ODYSSEUS_URL 和 ODYSSEUS_API_TOKEN 环境变量的会话都能使用这个技能。

整个接入依赖三个前提，均由 integrations/claude/README.md 给出：

• 一个可访问的 Odysseus 实例（地址形如 http://your-odysseus-host:7000，本机时即 http://127.0.0.1:7000，见 SKILL.md 的示例）；
• 装有 Claude Code 的终端环境，且装有 python3（技能包自带的辅助脚本 odysseus_api.py 依赖它）；
• 一个在 Odysseus 里创建的、带权限范围的 API Token（不是任意 Token）。

在 Settings > Integrations 中创建 Claude Agent 并获取 Token

操作路径来自 integrations/claude/README.md 的 User Flow：

1. 打开 Odysseus 的 Settings > Integrations。
2. 添加一个 Claude Agent（设置前端对应的标签为 "Claude Agent"，见 settings.js 中的 AGENT_CONFIGS.claude 配置）。
3. Token 生成后，页面会显示一组完整的设置命令，直接复制使用。
4. 在同一表单中切换允许 Claude 使用的工具开关——这些开关就是后面权限范围的来源，Token 的每个工具面（todos、email、memory、calendar、documents、cookbook）都会按这里的开关在服务器端做检查。

把 odysseus 技能包安装到 ~/.claude/

复制的设置命令与 integrations/claude/README.md 中展示的命令一致。下面按同样结构展开，其中 ODYSSEUS_URL 替换为你的实例地址（例如 http://127.0.0.1:7000），ODYSSEUS_API_TOKEN 替换为上一步生成的 Token：

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/

各条命令的作用：

• export 两个环境变量：这是技能包运行的全部凭据来源，Claude Code 会话中缺失其一时，技能定义会要求你先在 Odysseus Settings 里创建 Token 并暴露这两个值，而不是猜测凭据。
• mkdir -p ~/.claude：创建 Claude Code 的用户级配置目录（已存在时不会报错）。
• curl ... /api/claude/plugin.zip：使用 Bearer Token 从 Odysseus 下载技能包 zip。该端点由 routes/codex_routes.py 中的 setup_claude_routes() 提供，它只会打包 integrations/claude/skills/ 子树，避免把 README 等元数据解压进你的 Claude 配置目录。
• python3 -m zipfile -e ... ~/.claude/：把 zip 解压到 ~/.claude/，解压后得到 ~/.claude/skills/odysseus/，内含技能定义与辅助脚本。

Claude Code 会自动加载 ~/.claude/skills/ 下的内容，所以不需要额外的注册步骤；只要会话环境里有这两个变量，odysseus 技能就可用。

技能包里实际只有两样东西（见 integrations/claude/README.md）：

• integrations/claude/skills/odysseus/SKILL.md——Claude Code 读取的技能定义，描述了何时该用哪些 /api/codex/* 端点、哪些做法被禁止；
• integrations/claude/skills/odysseus/scripts/odysseus_api.py——一个小辅助脚本，负责带上 Bearer Token 调用有权限范围的 /api/codex/* 端点。这里要注意文档的说明：codex 路径是历史命名，由所有 agent 集成共用，Claude Code 运行时用的就是这套端点，/api/claude/plugin.zip 只是用来分发技能包的入口。

验证接入：用 capabilities 端点核对权限

安装命令的最后一步就是验证：

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

该命令实际发起 GET /api/codex/capabilities，返回当前 Token 的工具面权限图。对照 routes/codex_routes.py 中该端点的实现，返回内容包含各工具面的开关状态：todos 的 actions 列表、email 的 read/draft/send、memory 的 read/write、calendar 的 read/write、documents 的 read/write、cookbook 的 read/launch，以及 safety 段（email_send_requires_confirmation、destructive_actions_should_confirm）。逐项为 true 还是 false 完全取决于你在 Settings > Integrations > Claude Agent 表单里开了哪些工具开关。

拿到权限图之后，按 SKILL.md 的要求，在使用任何一个工具面之前先查 capabilities。例如 capabilities 中没有 email.read: true 时，不要尝试读邮件，而是回 Odysseus 设置里为这个 Claude Agent 打开 Email read 开关。

权限范围如何生效：403 是开关问题，不是绕过问题

SKILL.md 的 Safety 一节定义了接入后的运行边界，要点是：

• Token 是 scope-gated 的，每个工具面都在 Odysseus 服务器端检查，即使 Claude 尝试调用一个未授权的端点，也会得到 403，直到用户在 Settings > Integrations > Claude Agent 中启用对应的开关；
• 把 403 当作设置中有意配置的权限限制，不要用任何手段绕过它；
• 所有 Odysseus 数据访问必须走 /api/codex/* 这套带权限范围的 HTTP API，禁止用 SSH、Docker、直接 Python 导入、SQLite 查询、MCP 内部接口、浏览器 Cookie 或本地文件去读写用户数据；
• 操作范围保持在该 Token 的 owner 之内。

辅助脚本本身也在客户端强制这一点：odysseus_api.py 对任意请求路径做了检查，只要不是 /api/codex/ 前缀就直接拒绝（"refusing non-/api/codex path"）。环境变量缺失时它也会报错退出并提示在 Odysseus Settings 中创建 Token，不会尝试用默认值兜底。

接入后能做什么：几个典型调用

安装成功后，日常调用都通过辅助脚本完成。以下示例来自 SKILL.md，其中哪些能力可用仍以你 capabilities 输出为准：

# 待办事项（需要 todos 读写权限）
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py todos list
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py todos add "Follow up"

# 带自然语言时间的提醒——用 POST 形式传 due_date，
# 因为 todos add 快捷方式只设置标题
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py POST /api/codex/todos '{"action":"add","title":"Call dentist","due_date":"tomorrow at 5pm"}'

# 邮件读取（需要 email.read）
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py emails list 5
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py emails read UID

# 记忆（写入需要 memory.write）
python3 ~/.claude/skills/odysseus/scripts/odysseus_api.py GET /api/codex/memory

SKILL.md 还约定了"提醒 vs 日历事件"的判断规则：用户说"提醒我某时间做某事"时，应创建带 due_date 的 TODO（due_date 本身就是提醒，会通过用户配置的浏览器/邮件/ntfy 通道触发通知），而不是创建名为 "Reminder" 的日历事件——后者只是日历上的时间块，不会触发通知。due_date 支持 ISO 时间戳和 "tomorrow 5pm"、"next Monday 9am"、"in 2 hours" 这类自然语言，后端按用户时区解析。

对于调试启动失败的模型服务，技能还覆盖了 Cookbook 面（需要 cookbook:read/cookbook:launch）：cookbook tasks 查任务、cookbook output SESSION_ID 看日志尾部、cookbook stop SESSION_ID 停掉旧任务、cookbook serve 用白名单二进制（vllm/python3/sglang/llama-server/ollama/node/npx 开头）重启。serve 的命令校验会拒绝 cd、source 前缀和 &&、||、;、$(...) 等 shell 元字符，因此不能借这条路执行任意 shell。

排错时的判断依据

接入后的问题基本可以归到三类，文档中均有对应说法：

• 命令报缺失环境变量：odysseus_api.py 会打印缺的是 ODYSSEUS_URL 还是 ODYSSEUS_API_TOKEN，把对应值导出到当前终端会话即可，脚本不会替你猜。
• 返回 403：这是 Settings 中权限开关未打开的表现，去 Settings > Integrations > Claude Agent 打开对应工具开关，然后重新跑 capabilities 确认。
• 脚本拒绝执行某个请求：辅助脚本只接受 /api/codex/ 路径、20 秒超时的请求；网络层失败会打印 request failed 与原始错误，此时检查 ODYSSEUS_URL 是否指向了可达的实例。

限制方面需要注意：这套接入的边界就是 Token 的权限范围与 /api/codex/* 端点面，文档明确把"绕过设置与权限范围去直接访问数据"列为禁止模式——如果确实需要某个新权限，正确做法是回 Odysseus 设置里启用相应开关，而不是换一条访问路径。