setup-proxy

Setup Proxy — Agent Connection Configuration Wizard

You are helping the user connect an AI Agent client (Claude Code / CodeBuddy / Codex / WorkBuddy / dsh / Hermes / OpenClaw) to Memory Proxy.

Background Knowledge

Memory Proxy is an LLM request proxy that injects team memory/skills/knowledge before the request is forwarded to the upstream LLM. Each agent client has a different configuration file format and protocol:

Agent	Configuration File	Protocol	Special Requirements
claude-code	`~/.claude/settings.json`	Anthropic Messages	Write the 5 model variables in the env field
codebuddy	`~/.codebuddy/models.json`	OpenAI Chat	Append an entry to the models array
codex	`~/.codex/config.toml`	OpenAI Responses	TOML format, must be `wire_api = "responses"`
workbuddy	`~/.workbuddy/models.json`	OpenAI Chat / Responses	top-level array
dsh	`~/.dsh/settings.yaml` + `~/.dsh/.credentials.yaml`	OpenAI Chat (no /v1)	Two files + chmod 700/600
hermes	`~/.hermes/config.yaml`	OpenAI Chat	Requires header preselection (x-team-id/agent-id/task-id)
openclaw	`~/.openclaw/openclaw.json`	OpenAI Chat	Requires header preselection + allowPrivateNetwork

Script Location

Configuration write script:agents/skills/setup-proxy/setup-proxy.sh(relative to the repository root directory)

Execution Flow

Strictly follow the order below; each step must pass verification before proceeding to the next step.

Step 1: Scan existing configuration

First check whether the user already has a proxy configuration to avoid redundant entry:

# 检查 Claude Code
cat ~/.claude/settings.json 2>/dev/null | jq -r '.env.ANTHROPIC_BASE_URL // empty'

# 检查 CodeBuddy
cat ~/.codebuddy/models.json 2>/dev/null | jq -r '.models[]? | select(.url | contains("/codebuddy/")) | .url' 2>/dev/null | head -1

# 检查其他 agent 类似...

If a URL containing the proxy path is scanned (containing /claude-code/、/codebuddy/、/codex/ and other fragments),extract and display：

Proxy address (the part of the URL before /<agent>/ )
Instance ID (the segment of the URL after /<agent>/ )
User Key (the value of the corresponding field, displayed redacted with the first and last 4 characters)
Model ID

Ask the user: "Existing configuration detected, reuse it?"

Yes → skip to Step 3
No → continue to Step 2 for manual input

Step 2: Collect basic information

Obtain from the user in sequence:

Proxy address(including protocol + port, e.g. http://127.0.0.1:8096）
Instance ID(default default, generally no need to change for local deployment)
User Key(obtained from the API Key page of the panel, format not restricted)

Confirm each piece of information after obtaining it; do not ask three at once.

Step 3: Select Agent

Display 7 selectable agents for the user to chooseone：

Claude Code
CodeBuddy
Codex
WorkBuddy
dsh (DeepSeek Harness)
Hermes
OpenClaw

Step 4: Fill in the model ID

Tell the user:

This model ID must be a model supported by the Proxy upstream
Give common examples:claude-sonnet-4-20250514、claude-opus-4.7、gpt-5.5、deepseek-r1

Step 5: Health probe (key verification step)

According to the protocol of the selected agent, construct the corresponding curl probe request:

# Claude Code → Anthropic Messages
curl -s -w "\n%{http_code}" -X POST "${PROXY_HOST}/claude-code/${INSTANCE_ID}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${USER_KEY}" \
  -d '{"model":"'${MODEL_ID}'","messages":[{"role":"user","content":"ping"}],"max_tokens":1,"stream":false}'

# CodeBuddy / Hermes / OpenClaw → OpenAI Chat
curl -s -w "\n%{http_code}" -X POST "${PROXY_HOST}/${AGENT}/${INSTANCE_ID}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${USER_KEY}" \
  -d '{"model":"'${MODEL_ID}'","messages":[{"role":"user","content":"ping"}],"max_tokens":1,"stream":false}'

# dsh → OpenAI Chat 但不带 /v1
curl -s -w "\n%{http_code}" -X POST "${PROXY_HOST}/dsh/${INSTANCE_ID}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${USER_KEY}" \
  -d '{"model":"'${MODEL_ID}'","messages":[{"role":"user","content":"ping"}],"max_tokens":1,"stream":false}'

# Codex → Responses API
curl -s -w "\n%{http_code}" -X POST "${PROXY_HOST}/codex/${INSTANCE_ID}/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${USER_KEY}" \
  -d '{"model":"'${MODEL_ID}'","input":[{"type":"message","role":"user","content":[{"type":"input_text","text":"ping"}]}],"stream":false}'

# WorkBuddy → OpenAI Chat (更通用)
curl -s -w "\n%{http_code}" -X POST "${PROXY_HOST}/workbuddy/${INSTANCE_ID}/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${USER_KEY}" \
  -d '{"model":"'${MODEL_ID}'","messages":[{"role":"user","content":"ping"}],"max_tokens":1,"stream":false}'

Judge the result：

HTTP connection failure (000) → tell the user the proxy is unreachable, have the user check the address/port/service status,do not continue
2xx → completely normal, continue
4xx → proxy reachable (may be the form returned by session-init or an auth issue),display the response body for the user's reference, continue
5xx → the proxy has a problem,display the complete error response, ask the user whether to continue

Step 6: Header preselection (Hermes / OpenClaw only)

If hermes or openclaw is selected, additional header preselection information needs to be collected. These agents do not support interactive forms, so team/agent/task IDs must be prefilled in the configuration.

Preferred approach: fetch the list via the panel API and let the user choose

Ask the user whether to provide the panel backend address (default http://127.0.0.1:8125). If provided:

# 1. 先通过 auth/verify 拿 user_id
curl -s -X POST "${PANEL_URL}/api/v1/meta/auth/verify" \
  -H "Content-Type: application/json" \
  -H "x-tdai-service-id: ${INSTANCE_ID}" \
  -d '{"user_key":"'${USER_KEY}'"}'
# 从 .data.user.user_id 提取

# 2. 拉 Team 列表
curl -s -X POST "${PANEL_URL}/api/v1/meta/team/list" \
  -H "Content-Type: application/json" \
  -H "x-tdai-user-key: ${USER_KEY}" \
  -H "x-tdai-service-id: ${INSTANCE_ID}" \
  -d '{"user_key":"'${USER_KEY}'"}'
# 从 .data.items 展示让用户选

# 3. 拉 Agent 列表（带 owner_user_id 过滤）
curl -s -X POST "${PANEL_URL}/api/v1/meta/agent/list" \
  -H "Content-Type: application/json" \
  -H "x-tdai-user-key: ${USER_KEY}" \
  -H "x-tdai-service-id: ${INSTANCE_ID}" \
  -d '{"team_id":"'${TEAM_ID}'","user_key":"'${USER_KEY}'","owner_user_id":"'${USER_ID}'"}'
# 从 .data.items 展示让用户选

# 4. 拉 Task 列表
curl -s -X POST "${PANEL_URL}/api/v1/meta/task/list" \
  -H "Content-Type: application/json" \
  -H "x-tdai-user-key: ${USER_KEY}" \
  -H "x-tdai-service-id: ${INSTANCE_ID}" \
  -d '{"team_id":"'${TEAM_ID}'","user_key":"'${USER_KEY}'"}'
# 第一个选项始终是"本次不关联任务 (no-task)"

If the panel is unreachable or the user does not want to provide it, have the user manually fill in team_id / agent_id / task_id.

Additionally, a x-conversation-idis needed (one can be automatically generated, such as conv-20260820-xxxx）。

Step 7: Confirm the configuration file path

Tell the user the default path (see the table above) and ask whether to use the default path. If not, have the user fill it in.

Step 8: Call the script to write the configuration

After all information has been collected and validated,call the script's non-interactive modeto write the configuration:

bash agents/skills/setup-proxy/setup-proxy.sh --non-interactive \
  --proxy-host "${PROXY_HOST}" \
  --instance-id "${INSTANCE_ID}" \
  --user-key "${USER_KEY}" \
  --agent "${CHOSEN_AGENT}" \
  --model "${MODEL_ID}" \
  --config-path "${CONFIG_PATH}"

If it is Hermes/OpenClaw, append:

  --team-id "${TEAM_ID}" \
  --agent-id "${AGENT_ID}" \
  --task-id "${TASK_ID}" \
  --conv-id "${CONVERSATION_ID}"

Check the script exit code: 0 = success, non-0 = failure (show the output to the user).

Step 9: Verify the written result

After writing, read the configuration file to confirm the content is correct:

cat <config_path>

Show the key fields to the user for confirmation.

Step 9.5: Remind the user to switch models

Writing the configuration does not mean it takes effect, you must remind the user to switch to the Proxy model in the client for requests to go through the Proxy pipeline:

Agent	How to switch
Claude Code	No action needed,`settings.json` 's env is automatically loaded at startup
CodeBuddy	Switch the model in the dialog to proxy-memory-agent(i.e., the configured model ID)
Codex	No action needed,`config.toml` has already specified the model
WorkBuddy	Switch in the model selector to the corresponding model in the custom model list
dsh	No action needed,`settings.yaml` has already specified the model
Hermes / OpenClaw	Ensure the provider/model selected in the client points to the Proxy configuration

Be sure to tell the user: if the model is not switched, requests will not go through the Proxy, and memory/skill injection will not take effect.

Step 10: Asset import (optional)

After configuration is complete, ask the user: do you want to import this Agent's local assets (skills + conversation history) into team memory?

If the user chooses to import:

Panel URL, Team ID, Agent ID are required
If team/agent was already selected in Step 6, reusing it is recommended
Otherwise, have the user provide them

Then call:

PANEL_URL="${PANEL_URL}" TDAI_SERVICE_ID="${INSTANCE_ID}" TDAI_USER_KEY="${USER_KEY}" \
  tsx agents/asset-import.ts --source "${CHOSEN_AGENT}" --team-id "${TEAM_ID}" --agent-id "${AGENT_ID}"

If tsx is unavailable, prompt the user to run the command manually.

Error handling principles

Connection failure: clearly tell the user which step failed and give troubleshooting suggestions (check service status, port, network)
4xx response: the proxy is reachable but there is a business error; show the full response body to help the user determine whether it is a key error, unsupported model, or another issue
File permissions: before writing, check whether the directory exists/is writable; dsh requires chmod
Do not guess: if information is insufficient or the status is unclear, ask the user instead of assuming

Notes

Configure only one agent at a time; after configuration is complete, tell the user they can run it again to configure other agents
The script will automatically back up the original configuration file as .bak.<timestamp>
All of CC's model environment variables (HAIKU/SONNET/OPUS/SUBAGENT) will be uniformly set to the model selected by the user
Codex must switch to Plan mode (Shift+Tab) before the first conversation; this is a client limitation
dsh's URL does not include /v1, this is hardcoded by the client
Hermes/OpenClaw's x-conversation-id needs to be manually changed for each new conversation