ThatCrispyToast/claude-rc-api
GitHub: ThatCrispyToast/claude-rc-api
一个逆向工程的非官方 Python 客户端，用于以编程方式远程控制和操控 Claude Code 会话，充当 Web/移动应用的控制器角色。
Stars: 1 | Forks: 0
# claude-rc-api
非官方的 Python 客户端，用于 Claude Code Remote Control Web 服务，
通过对 Claude Code CLI 的逆向工程开发，并已在实时 API 上进行测试。
它能让你的程序实现 `claude.ai/code` 和 Claude 移动应用的功能：
列出、观察和操控在机器上运行的 Claude Code 会话。它连接的是
Web 应用使用的同一个 `/v1/code/sessions` endpoint 和 claude.ai OAuth token。
## 工作原理
Remote Control 负责中继，它不运行云计算。你本地的
`claude remote-control` 进程运行 Claude 并保持与
Anthropic 的出站连接；Web 应用和移动应用作为控制器，负责发送消息
并读取会话的事件流。本库正是扮演这个控制器的角色。
```
your script ──► POST /v1/code/sessions/{id}/events (send a message)
◄── GET /v1/code/sessions/{id}/events/stream (SSE: read the reply)
(claude.ai OAuth Bearer + x-organization-uuid, from ~/.claude)
```
它还提供了一个 `ManagedAgentsClient`，用于同类的公开 Sessions API
（`/v1/sessions`、`x-api-key`），该 API 会在 Anthropic 的云中运行 agent。
## 安装
作为库 / CLI，直接从仓库安装：
```
uv add "claude-rc-api @ git+https://github.com/ThatCrispyToast/claude-rc-api" # into a uv project
pip install "git+https://github.com/ThatCrispyToast/claude-rc-api" # into any venv
uvx --from "git+https://github.com/ThatCrispyToast/claude-rc-api[cli]" claude-rc list # run the CLI, zero install
```
如果在检出的代码中进行开发，请使用 [uv](https://docs.astral.sh/uv/)：
```
uv sync --extra cli # runtime + pretty CLI
uv sync --extra cli --extra test # + pytest
```
## 前置条件
1. 使用 claude.ai 账号 (Pro/Max/Team/Enterprise) 登录 Claude Code：
`claude` → `/login`。（API-key 登录无法使用 Remote Control。）
2. 准备一个要控制的会话：在某个项目中运行 `claude remote-control`（或者
`claude --remote-control`）。这会注册一个会话，然后你可以
从这里对其进行控制。
凭证会自动从 `~/.claude/.credentials.json`（OAuth token）
和 `~/.claude.json`（`organizationUuid`）加载。可以通过
`CLAUDE_RC_ACCESS_TOKEN` / `CLAUDE_CODE_OAUTH_TOKEN` 和 `CLAUDE_RC_ORG_UUID` 来覆盖它们。
## CLI
```
claude-rc whoami # login / org / token status
claude-rc list # your Remote Control sessions
claude-rc get # session details (JSON)
claude-rc events # recent history
claude-rc watch # stream live (read-only)
claude-rc send "run the tests" # send a message, print the reply
claude-rc repl # interactive chat
claude-rc web # browser control panel (all sessions)
```
## Web UI
一个无依赖的浏览器控制面板，用于你的 Remote Control 会话：列出
会话、查看实时事件流、发送消息，并进行操控（中断 / 设置
model / 设置权限模式 / 归档）。
```
claude-rc web # serves http://127.0.0.1:8765 and opens it
claude-rc web --port 9000 --no-open
```
它是一个基于标准库 `http.server`（无新增依赖）的服务，作为
`RemoteControlClient` 的代理。它使用*你的* OAuth token 与私有 API 通信，
并且自身不进行任何认证，因此默认绑定到 `127.0.0.1`。只有在
你接受任何能访问它的人都可以操控你的会话的前提下，才传递
`--host 0.0.0.0`。你也可以通过编程方式运行它：
```
from claude_rc import serve_webui
serve_webui(host="127.0.0.1", port=8765, open_browser=True)
```
## 库
```
from claude_rc import RemoteControlClient
rc = RemoteControlClient() # reads ~/.claude, refreshes token as needed
# 发现 sessions
for s in rc.sessions():
print(s["id"], s["status"], s["title"])
sid = rc.sessions()[0]["id"]
# 提问并等待回答（发送，从 pre-send cursor 流式传输，在 `result` 处停止）
for ev in rc.send_and_collect(sid, "summarize the current diff", print_stream=True):
pass
# 以只读方式观察
for ev in rc.stream_events(sid):
if ev.role == "assistant":
print(ev.text())
if ev.type == "result":
break
# steer
rc.interrupt(sid)
rc.set_model(sid, "claude-opus-4-8")
rc.set_permission_mode(sid, "acceptEdits")
rc.set_effort(sid, "high") # low|medium|high|xhigh, or None = auto
```
Cloud (Managed Agents) 模式：
```
from claude_rc import ManagedAgentsClient
ma = ManagedAgentsClient(api_key="sk-ant-...")
agent = ma.create_agent(name="A", model="claude-opus-4-8",
tools=[{"type": "agent_toolset_20260401"}])
env = ma.create_environment(name="e", config={"type": "cloud",
"networking": {"type": "unrestricted"}})
sess = ma.create_session(agent=agent["id"], environment_id=env["id"])
ma.send_message(sess["id"], "hello")
for ev in ma.stream_events(sess["id"]):
if ev.type == "agent.message": print(ev.text())
if ev.type == "session.status_idle": break
```
参见 [`examples/`](./examples)。
## 事件
`Event` 规范化了两种传输格式。对于 Remote Control，重要的 payload
类型有 `user`、`assistant`、`result`（回合完成）、`control_request`
（操控 / 权限提示）和 `system`（初始化）。辅助方法：
```
ev.type # payload type
ev.role # "user" | "assistant" | None
ev.text() # concatenated text blocks (handles str or block-list content)
ev.tool_uses() # tool_use content blocks
ev.sequence_num # RC ordering/resume cursor (int)
ev.is_turn_end # a `result` (RC) or `session.status_idle` (managed agents)
ev.is_blocking_control # a permission prompt waiting on you
```
## 安全性
- `list`/`get`/`events`/`watch` 以及所有 `RemoteControlClient` 的读取方法都是
只读的。`send`/`repl`/`send_message`/`interrupt` 会注入到实时
会话中，因此请仅在你拥有的会话上使用它们。
- Token 刷新会将刷新后的 token 写回到
`~/.claude/.credentials.json`（与 CLI 相同）。传入 `persist_refresh=False`
可将刷新保留在内存中。
- 本项目绝不会打印或传输你的 token。
## 使用方
[`claude-remote-bridge`](https://github.com/ThatCrispyToast/g2-claude-remote)
（Claude Remote 眼镜应用的 `server/` 部分）直接通过 git 依赖于此包，
并将 `RemoteControlClient` 封装在 JSON + SSE HTTP 桥接器中。它
导入 `client`、`credentials` 和 `events`，并在每次全新安装
`uv` 时解析此仓库的默认分支——因此请保持这三者的向后兼容性。
## 项目布局
```
claude_rc/
credentials.py # OAuth load + refresh, org uuid, ~/.claude parsing
client.py # RemoteControlClient (mode A) + ManagedAgentsClient (mode B)
events.py # Event model + builders for both wire formats
sse.py # dependency-free SSE parser
cli.py # `claude-rc` command line
webui.py # `claude-rc web` — stdlib http.server control panel
static/ # the web UI single-page app
API_REFERENCE.md # full reverse-engineered protocol reference
examples/ # runnable examples
tests/ # offline unit tests (pytest)
```
## 测试
```
uv run --extra test pytest -q
```
所有测试均在离线环境下运行（无需网络，无需凭证）。
标签：AI 会话控制, API 客户端, Claude Code, Python, 云资产清单, 文档结构分析, 无后门, 逆向工具, 逆向工程